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Preface 


This Language Reference Manual is one of two instruction manuals supplied with 
BASIC 2 Plus. The other is the User Guide and Quick Reference. 

This manual gives a detailed explanation of the BASIC 2 Plus programming 
language and of how the commands work. How to enter programs into your 
computer, how to save them and how to edit them using BASIC 2 Plus’s powerful 
mouse-driven editorare all explained in the User Guide. There is also a large section 
in the User Guide on the debugging tools available. 

The text of the Language Reference Manual is interspersed with shaded boxes 
which give a concise summary of the language. If you are an experienced 
programmer you may be able to leam BASIC 2 Plus from these boxes alone. 
Beginners, however, will need to read the text carefully, and only refer to the boxes 
later as they gain in experience. 

If you have programmed in BASIC 2, the predecessor of BASIC 2 Plus, you will 
notice some new facilities. Such structures as the SELECT CASE statement and 
the block IF statement make structured programming much easier. Routines are 
now implemented, and it is now possible for your program to be split into different 
program units - a main program and several modules. Read Chapters 5,6, and 7 for 
details. 

IMPORTANT: Before running any BASIC 2 program under BASIC 2 Plus, you are advised first to 
scan through the program in the Edit window to see if any of the variables are being 
shown in capital letter. If any are, then you will need to change the name of this 
variable because this name is now used as a BASIC 2 Keyword. 

You are also advised to use BASIC 2 Plus's Check-out option to 'Pre-scan' 
your program before running it (as described in the section on 'Programming' in 
Chapter 1 of the User Guide). 
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Conventions 




Anyone coming to a programming language such as BASIC 2 Plus for the first time needs a 
full explanation of its features. Once they are familiar with the language, though, they usually 
just need a quick reminder of how a particular command works; they don't want to plough 
through a detailed explanation to find what they need to know. 

Because of this, this manual is written on two levels. The main text gives a fairly friendly 
explanation suitable for someone new to BASIC (though some knowledge of programming is 
assumed). It describes all of the language's features, though it does not describe every 
possible variation in syntax - BASIC 2 Plus permits some very inelegant constructions in 
order to remain compatible with other BASICs. 

Interspersed among this text are a number of shaded boxes. They do contain every possible 
variation in syntax and they are written in a very compact style. While you re new to the 
language, you probably won't refer to these boxes much, but once you're familiar with a 
command and just need to use the manual for reference, the boxes are there to give a terse and 
accurate description of just what is and is not permitted. 


Typographic Conventions 


When describing a programming language in print, various conventions are necessary to 
indicate what typeface is used to represent various ways words and symbols are used. 

In this manual, anything which must appear in the program exactly as it appears in the 
manual is printed like this: 

PRINT "A Miss is as good as a Mile.” 

Words which represent other objects appear like this: 
numeric-expression 

So the manual might contain 
PRINT numeric-expression 



indicating that you should type the word PRINT followed by an expression which evaluates 
to a number. So, for example, you might type 

PRINT (28 + 291) * 14 
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This typeface is also used to represent words which have a special, technical, meaning. Some , 
words have obvious meanings, as in the case of filename. Others are not so obvious: formal-list, 1 
for example. But all technical terms used in this way are explained in the text, and they all 
have a box explaining their exact syntax. 

Any part of a statement which is optional is enclosed in italic square brackets, like this: 

[ LET ] trombones - 76 

and any part of a statement which can be repeated arbitrarily many times is followed by an 
ellipsis... 

decimal-digit ( decimal-digit ].~ 

This is commonly used after a square-bracketed option, to show that the option can be . 
repeated zero or more times. 

Finally, there are a few concepts which pervade so much of BASIC 2 Plus that they are 
collected together here, where they can easily be found. They are widely referred to, both in 
the boxes and in the text, though some of them merit extra explanation in an appropriate 
chapter. 


- 





Syntax 

or 


is 

where 


Description 


actual-array 

actual-array is array-identifier [ ( ) ] 

string-general-variable . record-identifier . vector-field-identifier l ( ) ] 

(The round brackets can be replaced by square) 

array-identifier 

An array-identifier is an identifier which is the name of an array. See Chapter 2 for 
details. 

expression 

[ unary]... primary [ operator[ unary]... primary]... 
unary is any one of +, - or NOT 

operatoris any one of A , *, /, MOD,.+, AND, OR, XOR, <, ", <>, >-, ">, > 

primary is general-variable 

or ( expression ) [selector]... 
or numeric-literal 
or string-literal [selector]... 
or function-call [selector]... 

Each primary in turn is evaluated, from left to right through the expression. The 
resulting values are then combined according to the following operator precedence: 

Precedence group Operators 


1 (highest) 

2 

3 

4 

5 

6 

7 

8 

9 (lowest) 


unary +, unary - 
* / \ MOD 
+ - 

<>,>-,->,> 

unary NOT 
AND 
OR 
XOR 


For more details, see Chapter 3. 
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field-selector 

is . record-identifier, simple-field 

or . record-identifier, vector-field! integer-expression ) 

or . record-identifier, vector-fieldl integer-expression ] 

where record-identifier is a name, and simple-field and vector-field are identifiers. 

A field-selector is used to select a field in a record value, the type of the result is the 
type of the field. For an explanation of records, see Chapter 2. 

filename 

A filename is a string-expression which evaluates to a valid DOS file name. 

formal-array 

Syntax formal-array is array-identifier ([,]...) 

The round brackets can be replaced by square) 

formal-list 

Syntax formal-list is formal-sublist[ separator formal-sublist ]... 

where formal-sublist is VAL simple-var-list 
or CONST simple-var-list 
or /VAR7 formal-var-list 

separator is , or ; 

simple-var-list is simple-variable (. simple-variable 7 ... 
formal-var-list is formal-var[, formal-var ]... 
formal-var is simple-variable or formal-array 

function-call 

is function[(parameter(, parameter ]...) 

where function is the name of a routine function, a built-in function or an expression 
function, and each parameter is a suitable form of parameter. 

For a full explanation of functions, see Chapter 6. 
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general-variable 

is simple-numeric-variable 

or numeric-array ( integer-expression [. integer-expression ]...) 
or numeric-array [ integer-expression[. integer-expression]...'] 
or simple-string-variable [selector]... 

or string-array ( integer-expression [, integer-expression ]...) [selector]... 
or string-array [ integer-expression [. integer-expression]...] [selector]... 

where numeric-array is a numeric-identifier which is the name of a numeric array. 

string-array is a string-identifier which is the name of a string array. 

identifier 

An identifier consists of a sequence of the following characters: 

Letters: 'a' to 'z\ accented letters and Greek characters 
Digits: ’O' to ’9' 

Characters: T,T 

An identifier must start with a letter. The characters T, '$’ may only be the 
last character in the identifier. 

integer-expression 

When an integer-expression is required this is a numeric-expression which is then 
rounded to the nearest integer. The result must be a value in the range - 
2147483648..+2147483647, otherwise an error is raised. 

label 

A label is a name. 

line-number 

is decimal-digit [decimal-digit]... 
where decimal-digit is one of 0,1, 2,3,4, 5, 6,7,8,9 

location 

A location is a label or a line-number. 
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name 


A name isany numeric-identifier, the term name is used when the identifier does not 
refer to a number. 

numeric-expression 

A numeric-expression is any expression which evaluates to a number. 

numeric-general-variable 

A numeric-general-variable is an general-variable which refers to a numeric value. 

numeric-identifier 

A numeric-identifier is an identifier which does not end in a $. 

numeric-literal 

is decimal-integer [(chaft]. [chaff] decimal-integer]] [[chaff] exponent] 
or . [chaff] decimal-integer[[chaff] exponent] 

or &[chalf] X [chaff] binary-digit [[_]... binary-digit],.. 

or &[[chaff] H] [chaff] hexadecimal-digit HJ...hexadecimal-digit]... 

where decimal-integer is decimal-digit [[chaff] decimal-digit]... 

exponent is E[[chaft] sign] [chaff] decimal-integer 

sign is + or - 

decimal-digit is one of 0,1, 2,3,4, 5,6, 7,8, 9 

binary-digit is one of 0,1 

hexadecimal-digit is one of decimal-digit, A, B, C, D, E, F, a, b, c, d, e, f 
chaff is space, tab, line-feed or _ 

selector 

A selector is a substring-selector or a field-selector. A selector selects part of a string value 
(so may not be applied to a numeric value). Where one selector follows another the 
selections are done in the order given (left to right), each operating on the string 
selected so far. 
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simple-numeric-variable 

A simple-numeric-variable is an numeric-identifier which is the name of a numeric variable. 

simple-string-variable 

A simple-string-variable is an string-identifier which is the name of a string variable. 

simple-variable 

A simple-variable is a simple-numeric-variable or a simple-string-variable. 

stream-number 

A stream-number is an integer-expression which evaluates to a number in the range 
0..15. 

string-expression 

A string-expression is any expression which evaluates to a string. 

string-general-variable 

A string-general-variable is an general-variable which refers to a string value. 

string-identifier 

A string-identifier is an identifier which ends in a %. 

string-literal 

is " [character]..." 

where character is any printing character from the GEM character set described in 
Appendix I. 
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{sfart) 

[startTO [finish]) 

[[start ]TO finish) 

[start. [finish]) 

[[start]. finish) 

start and finish are integer-expressions ; giving values in the range -4096..+4096. 

A substring-selector is used to pick out part of a string, the result is a string. For a full 
description see Chapter 4. 


A truth-value is a numeric-expression which is deemed to be True if it gives a non-zero 
value and False otherwise. 





Program Structure 


This chapter gives a broad outline of the structure of a BASIC 2 Plus program. Without going 
into any detail about the syntax of individual commands, it explains how the various 
components of a program are fitted together; it also shows some of the options available in 
laying out your code and explains how to take advantage of them. 

Much of the chapter assumes a knowledge of the fundamentals of programming. If you have 
no programming experience, you should skim through without trying to take in too much 
detail, especially about the technicalities. But if you have programmed before, especially in 
another BASIC, you will find the structure of BASIC 2 Plus straightforward and logical. 

The Elements of a Program 

A program consists of statements which comprise four different kinds of element: 

• keywords 

• identifiers 

• constants 

• punctuation and symbols 

Keywords are special sequences of characters which BASIC 2 Plus understands, and which 
tell it directly what you want. A complete list of keywords is given at the end of the User 
Guide; it includes words such as PRINT,CIRCLE and THEN. Keywords are automatically set 
in capital letters by BASIC 2 Plus's editor, and so they always appear in capitals in this guide. 

Identifiers are words which you make up to name constants, variables, routines (user-defined 
instructions) and other objects. Examples are limited only by your imagination, but you 
might use weekday}, stock, or bananas. It is common practice to use identifiers like a$ or 
foo, but this is not good programming style; it makes for much clearer programs if you use 
identifiers which have a meaning, and which indicate what the identifier represents. Using 
longer identifiers will not make your program run slower. 

Identifiers are set in lower case by the editor, so they are printed in lower case in examples in 
this guide. 

Constants (or literals) are numbers and character strings which the program interprets 
directly. There arc many different ways they can be included in a program (this particularly 
applies to numbers) and they arc described in detail over the next three chapters. 
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Statements 


Programs in BASIC 2 Plus consist of a sequence of simple statements and block statements 
arranged in lines of up to 2S5 characters. Simple statements are the most direct. Each line of 
the program may contain several simple statements, though the statements themselves arc 
never split across more than one line of the program. For example: 

bananas = 0 
and 

BOX #1. xbase;ybase, 100 + CEILING(top/20). 200 ROUNDED 

FILL ONLY WITH 3 

Block statements are much longer, and generally spread over several lines of the program. 
They may contain simple statements and other block statements within them. For example, 
here are two block statements, one inside the other: 

FOR warehouse - 1 to 5 

IF ( weekdays)[ checkdate ] - todays ) AND ( bananasf warehouse ] = 0) 
THEN PRINT "Order more bananas in warehouse warehouse 
ELSE stockf checkdate ] = stock[ checkdate ] + bananasf warehouse ] 
END IF 

NEXT warehouse 

The FOR block statement contains an IF block statement, which contains the simple 
statements 

PRINT "Order more bananas in warehouse "; warehouse 
and 

stockf checkdate ] = stock[ checkdate ] + bananasf warehouse ] 

Statements are separated either by new lines or by colons - or by both, since it is possible to 
have as many colons and new lines as you want between statements. This applies equally to 
statements forming part of the main sequence of the program, and statements contained 
within a block statement. It is a general rule in BASIC 2 Plus that all statements can be 
preceded (or followed) by any number of new lines or colons. (There is but one exception - 
statements which form part of a single-line IF statement They will be dealt with in 
Chapter 5.) 

Since statements can be followed by as many new lines as you wish, it follows that you can 
pul in blank lines in the middle of your statements. This is an excellent habit to get into, as it 
enables you to break up your program into sections, each with a specific purpose. When you 
read through the program, you will find it much easier to comprehend if there arc plenty of 
blank lines to reinforce the structure of what you have written. 
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Routines 
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Similarly, you can always start a line with any number of tabs or blank spaces. This can show f||||f 

structure, too, as demonstrated by the sample block statement above. 

A program typically ends with an END statement. This is not compulsory, as the program 
will stop when it runs out of statements to execute (it doesn’t have a lot of choice) but it is 
good style. 


BASIC 2 Plus has several features which enable you to write highly structured programs. 
One of the most important of these is the routine. There are two sorts of routine: subprograms 
(generally abbreviated to SUBs)and FUNCTIONS. 

SUBs and FUNCTIONS are groups of statements which can be executed by means of a 
single statement. This calling statement can either be in the main program, or in another 
routine. A SUB is a convenient way of grouping statements, cither for clarity or because the 
same group of statements needs to be executed many times. A FUNCTION returns a result, 
which can be used by the calling statement in the same way as BASIC 2 Plus's inbuilt 
functions, like MAX or LOG. 

SUBs and FUNCTI ONs are particularly powerful for two reasons. Firstly they have their own 
local variables, which can be kept separate from variables in other routines or in the main 
body. Even if the variables have the same name, an assignment made to a local variable will 
not affect a variable in another routine. 

Secondly, SUBs and FUNCTIONS can operate on formal parameters , special variables which 
arc tied to variables - actual parameters - in the calling statcmenL Formal parameters can be 
VAL-parameters, in which case the SUB or FUNCTION operates only on the value of the actual 
parameters; the actual parameters themselves cannot be changed by the action of the routine. 
Alternatively, the formal parameters can be VAR-parameters, which means that any change 
made to them inside the routine is automatically reflected in the actual parameters. 

SUB and FUNCTION definitions follow the main sequence of statements: the body of the 
program. They consist of an appropriate heading followed by a sequence of statements. Like 
statements in the program body, these statements arc separated by colons and new lines, and 
can be preceded by tabs and spaces. 

Routines and their parameters are one of the most important tools in writing well structured, 
intelligible programs. They are explained in detail in Chapter 6. 
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Modules 


A BASIC 2 Plus program may consist of several program units - a main program (sometimes 
just called 'main) and a number of modules. Modules arc stored in separate files from their 
main programs. This means that it is possible to write a module which can be used by many 
different programs - a library of mathematical functions, for example, or specific input and 
output routines. 

Like main programs, modules have a body (with global variables) and dependent SUBs and 
FUNCTIONS (with their own local variables). Unlike the local variables in routines, a module 
body's variables are preserved when control passes back to the calling statement. 

Modules may themselves call other modules. Their SUBs and FUNCTIONS can be made 
available to other program units if they are marked with the keyword EXPORT when they arc 
declared. Likewise, variables marked for EXPORT can be used by other program units. 
Corresponding to these exported variables and routines there must be an IMPORT block in the 
calling routine - a special part of the program which lists all the variables and routines a 
program unit expects to import from other modules. 

Modules are normally written in BASIC 2 Plus, but it is possible to write them in other 
languages. This is particularly important if a particular part of a program needs to run very 
quickly, or needs to be written very compactly. That part can be written in machine code and 
then called as a module from the main program. 

Machine code modules are invoked in exactly the same way as modules written in BASIC 2 
Plus, or in another language, such as C. So if different modules are written by different 
programmers, there is no need for the programmer who writes the calling routine even to 
know what language the module is written in. This is of great benefit when testing programs. 
It means that while you arc testing the main program, you can substitute a dummy test 
module in BASIC 2 Plus. When the main program is working properly, you can then 
substitute the machine code version of the module, and you will not need to make any 
changes to the main program. 

Line numbers and Labels 

In older versions of BASIC, line numbers and labels are all-important. In BASIC 2 Plus they 
arc all but redundant, and arc only used with a few special commands. You do not need a line 
number at the start of each line, and the line numbers you do have do not need to be in 
numerical order. 
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Any line of the program may start with a line number. Almost any line can have a label; the 
exceptions are lines which start with one of the keywords that must appear at the very 
beginningofaline, namely SUB, FUNCTION,MODULE,and IMPORT. 

Line numbers and labels are used to identify lines, not statements. If a statement starts in the 
middle of a line (separated from the previous statement by a colon) then it cannot have its 
own label - the label will apply to the whole line. 

Line numbers must be integers in the range 1 to 65534. Leading zeroes are permitted, but 
they will be ignored when the program is run: 00123 is the same line as 123. By way of 
example: 

250 bananas = 0 

Labels take one of two forms. They either consist of the keyword LABEL followed by an 
identifier, or an identifier with a colon appended. The first form must be separated from 
regular statements with a colon or a new line; the second form need not be. So a simple 
statement with a label could appear as: 

LABEL nofruit : bananas = 0 
or 

nofruit: bananas = 0 

Line numbers and labels are local to their routine. If a SUB or FUNCTION contains a label or 
line number, it will be considered distinct from an identical label or line number in another 
SUB or FUNCTION or in the main program. 

If two lines of the same routine (or two lines of the main program) are given the same label 
(or number), this will raise an error only when the label (or number) is referenced. It is not an 
error in itself to have two lines with the same label or number. 




LABEL 


Use 

This is used to define a label, which may be referenced by GOTO etc. 


Syntax 

LABEL label 


or 

label: 


Note 

When the first form is used (ie. with the keyword LABEL,) this is a statement in its 
own right, and must be separated from other statements with a colon or new line. 
When the second form is used (ie. appending a colon to the label) it must be used 

V- V- 


to prefix another statement. 
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It is good practice in programming to include notes explaining the structure of your program, 
what the variables represent etc. This is called documenting a program, and it helps anyone 
else reading it to understand it, and helps the programmer to remember how it works months 
later when coming back to it all. 

In BASIC, documentation is done with remarks, which are introduced with the keyword REM 
or an apostrophe. A remark can occupy a line by itself, or it can be appended to a line of code. 
In the latter case if the remark starts with REM it must be separated from the code with a colon. 
(The colon isn't necessary if the remark starts with an apostrophe.) 

After the REM or apostrophe, BASIC 2 Plus interprets any characters up to the end of the line 
as part of the remark, and they are ignored. For example, 

today - date + 1 ' set inventory date correctly 
or 

IF ( weekdays$[ checkdate ] - today} ) AND ( bananasf warehouse ] = 0) 

REM *** Yes, we have no bananas *** 

THEN PRINT "We have no bananas today" 

Because of the way BASIC 2 Plus scans the program before executing it, remarks do not 
slow the program down. You should not, therefore, be miserly with remarks except 
(possibly) to save space if your program is particularly large. 






Chapter 2 



Handling Information 


As far as a user of BASIC 2 Plus is concerned, there are just two types of information: 
numbers and strings. 

This is a great simplification over other BASICs, where the user has to choose how a numeric 
value is stored depending on how it is to be used. BASIC 2 Plus decides on the most 
appropriate way of storing a number, and converts it to the correct type for each operation as 
it is needed: eg. if an integer is required, the stored number is converted to an integer. 
BASIC 2 Plus also makes a point of using integer arithmetic automatically whenever it can, 
as this is faster. 

Sometimes, though, it can be a great benefit to the user to be able to specify how a variable is 
stored. (It is particularly important, for instance, when writing information out to a disk file.) 
For times like this, BASIC 2 Plus allows you to define 'storage classes’. These are explained 
in Section 2.4. In general, however, there is no need to worry about how numbers are stored, 
as this is taken care of by BASIC 2 Plus itself. 

(There is also the choice of whether floating point numbers arc handled as decimal numbers 
or as binary numbers. This is dealt with in the next chapter.) 

Numeric and string information are quite distinct and incompatible, having different 
behaviour and keywords associated with them. Facilities arc however provided to convert 
between the two types, where appropriate. 


2.1 Constant Information 



2.1.1 Numeric Constants 

Although BASIC 2 Plus selects the internal representation of various numbers it needs to 
store, there arc many ways numbers can be expressed when you type in the program. 

The simplest forms are the 'unsealed numbers', a term which comprises integers (eg. 666,0, 
740606, +3, -371) and real numbers (eg. 444.123, +3.000000000001, -999.9999) 

Both forms of unsealed number will probably already be familiar to you from everyday use 
Note that the numbers must not include commas, which you may be used to seeing in 
expressing large numbers, but may include spaces or underline characters instead. 
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Probably less familiar (unless you have a scientific background) arc 'scaled numbers' or 
'scientific formal' numbers. In these, the number is expressed as a positive or negative 
decimal number multiplied by 10 raised to a positive or negative power. In BASIC 2 Plus 
they take the form of an unsealed number followed by ifsignjnnn. For example, 1.0E6 denotes 
1 million (1 followed by 6 zeroes), while IE-3 denotes one thousandth (1 divided by 1000). 

Sealed numbers arc mainly used for expressing very large and very small numbers, in science 
and technology. For example, the speed of light is approximately 2.998E8 metres per second. 

Finally, you can express integers in binary or hexadecimal. These "Based Numbers" will 
mainly be of interest if you are used to programming in machine code. Binary numbers start 
with &X. Hexadecimal numbers start with & (or &H) followed by numbers in the range 0-9 
and letters A - F corresponding to 'digits’ of 10-15. The underline character may be used in 
based numbers to break up long strings of digits. As an example the numbers 12,255, and 0 
would be written in binary as &X1100, &X11111111 and &X0. The numbers 20,255, and 
7167 in hexadecimal would appear as &14, &FF, and &1BFF. 

Binary and hexadecimal integers greater than &7FFF_FFFF are treated as negative, 
following the two's complement convention for 32-bit representation. Thus, &FFFF_FFFE 
is-2. 

It is important to realise that these different representations of numbers only affect the way 
the numbers appear in the program listing. When the program is run, and the number is stored 
in the computer's memory, the original representation is forgotten. 

2.1.2 String Constants 

A string (or 'text string 1 ) is a sequence of byte values, each usually representing a printable 
character. (For a full list of characters and their codes, see Appendix I.) Strings can be 
between 0 and 4096 characters long. 

To distinguish a string constant from anything else it must start with double quotes (’) and 
end either with double quotes or an end-of-line. Typical strings are: 

"The Hitchhiker's Guide to the Galaxy" 

"Catherine Louise, spinster of this parish" 

•••• 

"23" 

The third example string has zero length and is called a null string. The last string is only a 
string because it is enclosed in quotes; without the quotes it would be the number 23. 

Most of the characters that you will want to use can be typed directly from the keyboard. 
Other characters can be created using BASIC 2 Plus functions. 
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2.2 Variables 


Information is stored in variables. A variable is simply an area of memory which has a name 
associated with it 

In line with the two different types of information (numeric and string), there are also two 
different type of variables - numeric variables and string variables. String variable names 
must end in a $; numeric variable names must not. 

Different amounts of memory are associated with each type. Strings are allocated enough 
bytes to hold the whole string; numbers are stored in 8 bytes (though this can be altered when 
the numbers are stored in arrays or records - see the description of 'Storage classes'). 

The value of any variable is undefined until specifically set If you use an undefined variable 
in a BASIC 2 Plus main program (though not in a module) its value will be taken as 0 (if it is 
a numeric variable) or the null string "" (if it is a string variable). 

However, such a convention can lead to extremely elusive bugs if you mistype a variable 
name, and for this reason you are recommended to have an error signalled when you use an 
undefined variable; you can do this by including an OPTION TRAP statement in the body of 
your main program. OPTION TRAP is implicitly set automatically within modules. 


Declaring Variables 

A variable is declared when it is named in a DIM, CONST, or EXPORT statement In addition, it 
is declared if it is named in a SHARED statement in a program or module body (not a routine). 
If none of the above statements is appropriate, the variable must be declared explicitly with a 
DECLARE statement This takes the form 

declare variables 

where variables is a list of simple-variables and formal-arrays, separated by commas. ( simple- 
variables are the names of ordinary variables, as defined in the next section; a formal-array 
specifies the name of an array and its number of dimensions. Arrays are explained later in this 
chapter, and formal arrays are defined precisely in Chapter 6.) 

As a further precaution against mistyping, you can include OPTION DECLARE in your 
program. This statement forces you to declare all variables before you can use them. 
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DECLARE 

Use DECLARE declares simple variables and arrays. 

Syntax DECLARE dedared-objecl [. dedared-objecl ]... 

where declared-object is simple-variable 
or formal-array 

Description A common error in BASIC programs is the simple mis-typing of a variable name. 

If OPTION DECLARE is specified all names of variables must be declared in some 
way. For simple variables this DECLARE statement is the required declaration. 

The statements SHARED (in a program or module body), DIM, CONST and EXPORT 
are also valid declarations. 

In an IMPORT block DECLARE imports simple variables and arrays. 


Constants 


BASIC 2 Plus provides "named constants". These arc just like variables, except that they may 
only be assigned to once, and then only in a CONST statement. It is always an error to use a 
constant before it has been defined by executing the relevant CONST statement. 

2.2.1 Variable names 

BASIC 2 Plus leaves the choice of variable name largely up to the programmer, though the 
name must not be the same as a keyword. (A full list of keywords is given at the end of the 
User Guide, though you can easily tell if you have used a keyword by accident, as the editor 
will automatically set it into capitals for you.) 

The name may include any of the following characters: 

- the letters'a'to'z' 

- accented letters and Greek letters. These may however cause problems when using 
certain printers to list programs. 

- the underline characterand numbers'O' to '9' in any position other than the first 
character 

In addition, the name may finish with a 'type suffix'. If the variable being represented is a 
string variable, then the variable name must have the type suffix $. In the case of a numeric 
variable, the variable name may have the type suffix %,! or# but, unlike other BASICs, these 
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type suffices are neither obligatory nor do they have any special meaning: they are treated 
simply as an extra character in the name. Thus, for example, i X and i are different variables. 

There is no restriction on the length of a variable name other than the limit to the length of a 
BASIC 2 Plus statement (255 characters). 

By way of example, the following are valid variable names: 
str84ward 

sane_mind_and_body 

Surnames 

corned_beef# 

But the following are not: 

4tune8 - starts with a numeral 

index - identical to a keyword 

getllost -! used other than at the end of a name 

titles held - name includes a space 

Capital and lower case letters are considered equivalent in variable names, so the variable 
'SumameS' is the same as 'sumameS', 'SURNAMES' etc. In fact the BASIC 2 Plus editor 
changes all letters to lower case except in keywords, which are automatically set in capitals. 

2.2.2 Lifetime of variables 

Once a variable has had a value assigned to it, this value will be retained until either another 
value is assigned or the variable becomes undefined. The point at which a variable becomes 
undefined depends on the part of the program in which the variable is created. 

Local variables created inside routines (subprograms and functions - see Chapter 6) become 
undefined the moment the routine is left. 

Global variables (created in either the main program or modules) and variables created in the 
Dialogue window become undefined when you: 

• Use NEW, either from the menu, or by typing it directly into the dialogue window 

• Type CLEAR in the Dialogue Window 

• RUN a program (including the same program) 

• load a program 

• leave BASIC 2 Plus 

In addition, global variables in modules become undefined when the module is unloaded - 
see Chapter 7. 
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Note that global variables in the main program and in any modules which have not been 
unloaded retain their value after the program finishes. 


Variables also retain their current value when the program is stopped - either by the user or as 
a result of an error. This allows you to use BASIC 2 Plus in Direct mode to discover the 
current value of variables used within the program: this is very useful when developing and 
debugging programs. Note that variables are lost, and the program cannot continue, if the it is 
then edited - a warning is displayed, which offers the option to abandon the edit and retain 
the variables. BASIC 2 Plus has "debug points" which may be used to add extra statements, 
without affecting the variables, or the ability to continue execution. (For more details, see 
Chapter 4 of Part 1 - 'Debugging'.) 


2.3 Assignment 


Information is stored by assigning it. 

At the heart of an assignment statement is an equals sign; the information to be stored is 
written on the right of the equals sign, and the place the information is to be stored on the left. 
On the lefthand side of an assignment statement you can put a "general variable" which may 
be any one of: 

• a simple variable 

• an array element 

• a substring, or 

• a record field 


These items feature as a group in many parts of BASIC 2 Plus, for example, they appear 
along with arrays and vector fields as routine parameters (see Chapter 6). It is therefore useful / 
to refer to them collectively as 'general variables' (to indicate that this encompasses the full 
generality of what is treated as a variable). 

The righlhand side of the assignment must be an expression - a numeric expression if the 
assignment is to a numeric general variable, and a string expression if the assignment is to a 
string general variable. (The exact definition of an expression is rather complicated: details 
are given in the next chapter.) A general assignment statement, then, looks like this: 

general-variable = expression 

You can precede this assignment statement by the keyword LET. 

' i 


o 
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LET 

Use 

LET assigns the value of an expression to a general-variable. 

Syntax 

/ LET ] general-variable - expression 

Description 

Firstly, any substrings or array indices in general-variable are evaluated. Next, 
expression is evaluated. When the evaluation is complete, the value of expression is 
assigned to general-variable. 


general-variable and expression must be of the same type - ie. both numeric or both 
string. 

Alternative use 

LET may be used to assign the return code from a statement to a general-variable. 

Syntax 

/LET/ numeric-general-variable - statement 

Description 

Firstly, any substrings or array indices in numeric-general-variable are evaluated. 

Next, statement is executed, if possible. If the execution is successful, 0 is assigned 
to numeric-general-variable ; if the execution was not successful (or only a qualified 


CONST 

Use 

CONST declares and sets named constants. 

Syntax 

CONST simple-variable - expression (. simple-variable - expression]... 

Description 

Each simple-variable is set to the result of the corresponding expression- the two 
must agree in type. ! 


All simple-variable s which are assigned to in CONST statements are "named 
constants:". These behave exactly like variables except that firstly, they may not 
be used before the relevant CONST statement has set their value, and secondly, 
they may not be assigned to - other than in the relevant CONST statement. It is an 
error to execute a CONST statement more than once. It is also an error to have 
more than one CONST for the same named constant. ; 
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The following are examples of assignment statements: 

title$ - "The Fall of the House of Usher" 
average - (first + second + third) / 3 
fruit - apples + oranges 

You can assign to a variable as often as you like. You can also use the general variable in the 
expression which is being assigned to it (its value will remain the same until the entire 
expression has been evaluated). For example: 

count - count + 1 

The values for named constants are set using the statement CONST: 

CONST simple-variable - expression 

which assigns the result of the expression to the simple variable. This variable may never be 
assigned to again - so it is a constant! 

Values held in two variables can be swapped directly, using the statement SWAP: 

SWAP general-variable-1 . general-variable-2 

statements 

Information can also be held in a program in lists, using the keyword DATA; R EAD is then used 
to read the values into general variables. 

DATA is followed by one or more numbers or strings separated by commas. For example: 
DATA 11,7,56,April is in my mistress' face.666.21.-3 

You may have as many DATA statements as you like, within the main program and within any 
modules (though not in routines). They can be positioned wherever you like in the program 
body - BASIC 2 Plus will not attempt to execute them (they will just be skipped over) - but 
DATA must always be the last statement on a program line. 

Note that double quotes (") are not generally necessary round strings: 

DATA What is this thing called love? 

However they are necessary if the string includes commas, leading spaces or trailing spaces: 
DATA "What is this thing called, love?" 

You may however prefer to use quotes all the time, to be sure. 
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SWAP 

Use 

SWAP exchanges the values Of two general variables. 

Syntax 

SWAP general-variable-1, general-variable-2 

Description 

SWAP exchanges the values held in the two general-variables. They must be of the 
same type - ie. both numeric or both string types. 


SWAP Is directly equivalent to 

tempi - generahvariablel 
tempZ - general-variable2 
general-variable1 - temp2 
general-variable2 - tempi 

DATA 

Use 

OATA is used to include numeric or string data in the code of the program itself, 
rather than inputting it at run time. 

Syntax 

DATA [data-literal]]. [data-literal]]... 

where 

data-literal is signed-numeric-literal \ 

or string-literal 

or first-char([character]... last-char] 

where 

first-char is any printable character excluding space, comma & double quotes 
character is any printable character excluding comma 
last-char is any printable character excluding space & comma 

The DATA statement must be the last statement on a program line. 

Description 

The data-literals in a DATA statement may be read into general-variables at any 
time by means of a READ statement. 

DATA statements may not appear in SUBs, FUNCTIONS or IMPORT blocks. 

See also: 

READ 
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Information is read from DATA statements using the statement READ, which is followed by 
one or more general variables separated by commas. For example: 

READ cats, dogs, owner_name$ 

READ reads information from DATA statements in order, starting with the first item in the first 
DATA line. Attempting to read past the last DATA item in the program, or attempting to read a 
badly formed constant into a numeric variable will produce an error. 

READ and DATA are a good way to initialise arrays. For example, to set up an array called 
'days' with the number of days in each month: 

DIM days(l TO 12) 

DATA 31,28.31.30.31.30.31.31.30.31.30.31 
FOR count = 1 TO 12 
READ days(count) 

NEXT count 

Contrast this with assigning each value in turn: 

DIM days(l TO 12) 

days(l)-=31 

days(2)=28 

days(3)«31 

days(4)=30 

etc., up to 

days(12)-31 

READ normally reads each item in turn, advancing to the next DATA line when the last item in 
the present line has been read. The RESTORE statement allows you to alter this. 


READ 

Use READ is used to read data from a DATA statement into general-variables. 

Syntax READ general-variable [, general-variable ]... 

Description Every program unit in a BASIC 2 Plus program maintains a pointer into its DATA 
items. READ reads these DATA items into its general-variable s, beginning at the 
DATA item indicated by the pointer. As each DATA item is assigned to an general- 
variable, the pointer is advanced, ready to read the next DATA item into the next 


See also: RESTORE 
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RESTORE 



Description When used without a location, RESTORE moves the pointerto the first data-literal 


defined in a DATA statement in that program unit. 

When used with a location, the next READ will read from the beginning of the DATA 
statement at or after the specified location. 

RESTORE on its own continues reading from the start of the first DATA line. RESTORE 
followed by a location (line number or label), continues reading from the start of the first 
DAT A line at or after that location. The normal use of RESTORE is to allow you to re-read data 
which has already been assigned. However it is also possible to use RESTORE to miss DATA 
statements out by specifying a location later in the program than the current READ position. 


2.3.2 Assigning Return Codes 


When any BASIC 2 Plus statement is executed, a 'return code' indicates the success or failure 
of the execution. A return code of 0 indicates an unqualified success, a value from 11 o 99 
indicates a qualified success (that is, there were some problems, but not enough to halt the 
program) while a value of 100 or more indicates something seriously wrong. This is called 
"assigning a statement". 

In general return codes less than 100 are discarded, while the others are raised as errors which 
will normally stop the program. However, if the statement appears as the right hand side of an 
assignment, the return code will be assigned, and no error will be raised. For example: 

return_code - READ oldstock. currentstock. profit 

This will attempt to perform the READ statement, and assign its return code to the variable 
retu rn_code. If there are no problems, the READ statement will be executed normally and 
retu rn_code will take the value 0; if there is some reason why the READ statement cannot 
be executed properly (perhaps the corresponding DATA statement contains strings instead of 
numeric data) the READ statement will be abandoned when the error is detected and 
return_code will take value of the error number. In neither case will the program stop, 
even if error trapping has been set with an ON ERROR ... command (see Chapter 16). 

If an assignment statement is itself to be assigned, it must start with the keyword LET to 
prevent ambiguity: 

return_code = LET count = count + 1 
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2.4 Structured storage 


2.4.1 Arrays 


Variables are normally quite independent, but you can organise them into two types of larger 
structure: arrays and records. Arrays are used for grouping variables which are all of the same 
type: a block of strings, or a block of numbers. Records are used for grouping related 
variables which may be of different types: a person's name, age, address and income, for 
instance. 


An array is a block of variables of the same type all held under one name. 



The array as a whole is referred to by that name followed by a pair of brackets, for example: 
cats() 



The individual variables which make up the the array are referred to by the same name, but 
followed by a pair of brackets containing array indexes separated by commas, for example: 

cats( 7,4) 

Any array must always have the same number of array indexes; this is the number of 
'dimensions' of the array. The array-indexes are integer-expressions, ie. numeric-expressions 
which are rounded to the nearest integer when evaluated. 

The array name can be any valid variable name, for example: 
a$() 

transactions_to_date//() 

An array name ending in a $ indicates string variables; otherwise, they are numeric variables. 

You can use round brackets ( ) or square brackets [ ] for the array index. You may prefer 
to use square brackets, as this helps to distinguish array variables from function calls. 



Defining the number of elements in an array 



An array should usually be defined before use, using the statement DIM. This is followed by 
the name of the array and a specification of the bounds of each index: 

DIM identifieri index-bounds[. index-bounds]...) 

You may define several arrays in a single DIM statement by separating them with commas. 
For example: 

DIM cats( 10. 10 ). dogs(5) 
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DIM 

Use DIM is used to specify the size and number of elements in one or more arrays. 
Syntax DIM array-declaration[, array-declaration]... 

where array-declaration is array-name ( dimension-bounds[, dimension-bounds]...)[storage-class] 
array-name is an identifier giving the name, and type, of the array 
dimension-bounds is [lower-bound TO ]upper-bound 

where lower-bound and upper-bound are both integer-expressions giving values in the 
range -32768..32767 and lower-bound<= upper-bound. 

storage-class is integer-class /KEY/ 
or IEEE4 orIEEE8 


or FIXED length 

where integer-class is one of BYTE, UBYTE, WORD, UWORD, INTEGER 
length is an integer-expression giving a value in the range 1 ..4096. 

Note that throughout the DIM statement the round brackets may be replaced by 
square brackets. Note also that the FI XED storage class is the only class which 
may be applied to string arrays, and it may only be applied to string arrays. 

Description For each array-name in the statement, an array is defined. If the array name ends in 
a $, the array is an array of string variables; otherwise it is an array of numeric 
variables. 


The number of dimension-bounds inside the brackets defines the number of 
dimensions of the array. 


If dimension-bounds consists of two integer expressions separated by TO, it gives the 
lower and upper limits to the range of that dimension. If dimension-bounds consists 
of a single integer expression, it gives the upper limit; in this case the lower limit is 
taken to be 0. 


If there is a DIM statement for an array then it must be executed before the array 
is used. It is an error to execute a DIM statement more than once. It is also an 
error to have more than one DIM for the same array. 


BASIC 2 Plus: Language Reference 





















This use of DIM assumes that the lower bound is lo be 0, so that in the above example, the 
'first'element of the array cats( , ) willbecats(0,0).DIM dogs( 5) defines the array 
dogs() as having six elements. To have a different starting element, specify the index 
bounds as a range of elements, using TO: 

DIM dogs (first TO last) 

The first element in the array will be numbered first, the last will be numbered last, first must 
be less than or equal to last Negatively numbered elements are allowed, but indexes must be 
in the range -32768 to 32767. 

An array can have up to 7 dimensions. Each dimension is specified separately in the DIM 
statement, separated by commas. For example, to specify a three-dimensional array of 
10x10x5 called 'temperature' (This array might be used to store the average temperature of 
each cubic metre of air within a sports hall measuring 10x10x5 metres.): 

DIM temperatured TO 10, 1 TO 10, 1 TO 5) 

You do not have to dimension an array, but this is a good habit to get into. If you use an array 
without dimensioning it, the array will be set up with the required number of dimensions, 
each of which is taken as 0 TO 10. 

You must not have more than one statement which dimensions the same array, even if you 
make sure that only one of the statements is ever executed. An array which is explicitly 
dimensioned may not be used until the relevant DIM statement has been executed. 

Determining the dimensions of an array 

Once an array has been defined, the number of dimensions it has and the lower and upper 
bounds in each dimension can be determined by using the functions DIMENSIONS, L80UND 
and UB0UND. 

To determine the number of dimensions, use: 
result- DIMENSIONS ( array ) 

To determine the lower bound of one of these dimensions, use: 
result - LB0UND ( array [.index-number]) 

To determine the upper bound of one of these dimensions, use: 
result - UB0UND ( array /. index-number]) 

array will be the name of the array; followed by a pair of empty brackets, for example 
room_dims - DIMENSIONS! temperature () ) 

index-number is an integer-expression giving the number of the dimension: for example, details 
about the second dimension of an array will be given if the index-number 2 is specified. 
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Use 

Syntax 

Description 

Use 

Syntax 

where 

Description 


Use 

Syntax 

where 

Description 


DIMENSIONS 

DIMENSIONS is a function that determines the number of dimensions of an array. 
DIMENSIONS! actual-array) 

DIMENSIONS returns the number of dimensions of the specified array. It is an 
error to apply DIMENSIONS to an array for which there is a DIM statement, but 
that statement has not been executed. 

LBOUND & LOWER 

These functions may be used to determine the lower bound of one of the 
dimensions of an array. 

LBOUND (actual-array (, index-number]) 

LOW E R ( actual-array [, index-number]) 

index-number must be an integer-expression. in the range 1 to 7. 

LBOUND and LOWER return the lower limit of one dimension of the specified array. 
The dimension is specified by index-number, so that if index-number is 2, the lower 
limit of the second dimension is given. If index-number is omitted it is taken to be 1. 

It is an error to apply LBOUND or LOWER to an array for which there is a DIM 
statement, but that statement has not been executed. 

UBOUND& UPPER 

These functions may used to determine the upper bound of one of the dimensions 
of an array. 

UBOUND! actual-array [. index-number]) 

UPPER! actual-array [, index-number]) 

index-number must be an integer-expression. in the range 1 to 7. 

UBOUND and UPPER return the upper limit of one dimension of the specified array. 
The dimension is specified by index-number, so that if index-number is 2, the lower 
limit of the second dimension is given. If index-number is omitted it is taken to be 1. 

It is an error to apply UBOUND or UPPER to an array for which there is a DIM 
statement, but that statement has not been executed. 


i-v,' 
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Limiting the memory usage 

Each element in an array normally uses the same amount of space as the equivalent numeric 
or string variable. 

You can limit the amount of memory used by specifying a 'storage class' for the array as 
follows: 

DIM identified index-bounds [ , index-bounds ] ...) storage-class 

(Details of the different storage classes are given in 'Memory usage and storage classes' later 
in this chapter.) 

Specifying a storage class defines the number of bytes to be used for each element in the 
array. The saving this makes is readily calculable for numeric arrays (where each clement 
would normally take 8 bytes) but is not so well defined for string arrays: however, there is 
certainly a saving to be made if none of the elements of a suing array is more than 6 
characters long. 

t 

Using arrays 

It is possible (though perhaps unwise) to have a simple variable with the same name as an 
array; in this case the simple variable and the array are treated as quite distinct objects. One 
consequence of this is that arrays cannot be processed as single entities - for example, if you 
have set up arrays cats and rats with the statement 

DIM cats(3). rats(3) 
then the assignment 
cats - rats 

will not assign one array to the other - it will assign the current value of the simple variable 
rats to the simple variable cats. 1 

If you do need to make one array equal to another, the elements must be assigned 
individually: * 

for loopcount = 0 to 3 
cats(loopcount) - rats(loopcount) 

next loopcount • 

However, arrays can be passed as a whole to subprograms and functions: for details, sec 
Chapter 6 'Routines'. * 


i 
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2.4.2 Records 

The other way of organising variables is in structures known as records. 

A RECORD statement lays down a structure for the record, defining the names and sizes of its 
constituent variables Cfields'), specifying whether they are string or numeric variables, and 
what their storage class is to be. Once a record structure has been defined with a RECORD 
statement, you can define as many records of that structure as you like, and assign different 
values to each of them. The RECORD statement only lays down the structure of a record; it 
doesn't allocate any storage space. 

The record structure can be used anywhere in the main program - including in subprograms 
and functions - though not in modules. However, record structures cannot be defined in 
subprograms or functions (though they can be defined in the body of a module in which case 
the record structure will be local to the module). 

Defining record structures 

The RECORD statement takes the form: 

RECORD record-name: fields 

The record-name can be any valid name. It will be entirely distinct from anything with the 
same name. 

The fields part of the RECORD statement is simply a list of the names to be associated with the 
individual variables in the record, separated by commas and qualified by a storage class 
where appropriate. 

Each field can be handled as a variable in its own right, but a sequence of similar variables 
(same type and same number of bytes) can form a vector Held. This is effectively a single- 
dimensional array within the record and it is handled as such: each variable within the vector 
field has the same name but is identified by its array-index. 

Vector fields can be specified in any of the ways used for single-dimensional arrays - ie. 
either by just giving the index of the last item in the array (so that the first item has index 0) or 
by giving the dimension as first TO last. For example: 

RECORD mountain ; height , gridref , rainfal1(1980 TO 1995) 

The structure of any record has to be rigid to work. So when you include string variables they 
must be specified as having fixed length: 

RECORD mountain : name$ FIXED 20. height , gridref . 

rainfal1(1980 TO 1995) 


I9» 
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However, this requirement docs not prevent the record structure from being determined by 
the program itself: specifically, the bounds on the index of a vector field and the lengths of 
fixed strings can be defined by expressions whose value is not known until the RECORD 
statement is executed. 

A field, then, can be any of the following: 

name [storage-class] 

namei index-bounds) [storage-class] 

names FIXED length 

names (index-bounds) FIXED length 

Note that field names are local to a record structure, so you can use the same name for fields 
in different record structures. They are also entirely distinct from other variable names. 

When working in Binary Arithmetic mode the range of values which may be written to an 
unqualified numeric field (no storage class) is less than the full range of binary values - fields 
are restricted to approximately 110 4200 , where the full range is approximately tlO 1308 . This is 
because records may be written to disc, which means that the contents of a field may have 
been written by any of BASIC 2 (with its own 5 byte number form), BASIC 2 Plus working 
in Binary Arithmetic mode or BASIC 2 Plus working in Decimal Arithmetic mode. The 
restriction in the range for binary values allows the field to be encoded so that no matter how 
the number is written the reader can decipher it. Values arc written to fields in the current 
Arithmetic Mode form. Note that while BASIC 2 Plus can read fields written by BASIC 2, 
the converse is not true. (Sec Chapter 3 for the discussion of Binary and Decimal Arithmetic 
modes.) 


Using records 

The record structure defined in the RECORD statement does not create a variable; it only 
defines a structure. This structure can be imposed on any string or string variable in the 
program. Each field can be accessed, or the whole record can be manipulated exactly like any 
olher string. In the case of a string variable, individual fields can be assigned to, or the whole 
siring can be manipulated as one entity. 

To impose a record structure onto a siring, follow the siring wilh "field selector" which is a 
dot, then the record name, then another dot, then the field name, thus: 

string . record-name . field-name 

This combination of siring, record name and field name can be used exactly as if it were of 
the same type as the field. Similarly, vector fields can be used in all the same ways as an 
equivalent single-dimensional array. 
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Description 


RECORD 


Use 


Syntax 

where 


RECORD is used to specify a record structure which can be imposed on strings. 

RECORD record-name ; field-definition[. field-definition]... 
field-definition is: numeric-field-name [ vector-field][storage-class] 
or: string-field-name[vector-field /FIXED length 
numeric-field-name is a numeric-identifier, giving the name of a numeric field 
string-field-name is a string-identifier, giving the name of string field 
vector-field is ( dimension-bounds ) 
or [ dimension-bounds ] 

storage-class is integer-class /KEY ] 
or IEEE4 orIEEE8 

where integer-class is one of BYTE, UBYTE, WORD, UWORD, INTEGER 
length is an integer-expression giving a value in the range 1 ..4096. 


RECORD specifies a record structure which can be imposed on strings. The 
structure's name is record-name. 


The statement names and specifies each field in the record. 


If the field name is followed by parentheses, it is a vector field; its range is 
specified by the dimension-bounds within the parentheses, in exactly the same way 
as a single-dimension array is specified with the DIM statement. 


Records must be defined, by executing the relevant RECORD statement, before 
they are used. It is an error to execute a RECORD statement more than once. It is 
also an error to have more than one RECORD statement for the same record. 
RECORD statements may only appear in the body of the main program or of 
modules. Once a record is defined it may be used anywhere in the program or 
module in which it is defined - but not outside it. 
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For example, suppose you declare (he structure: 

RECORD person; name* FIXED 20. salary UWORD, address$(2 TO 5) FIXED 25 

You can then define a string variable worker) and assign to its individual fields with 
statements such as 

worker).person.namel) = "Old MacDonald" 
worker).person.salary = 5000 
worker).person.grade)(3) = "C" 

Information can be assigned to the fields of a record string in any order. 

You can also use any field of worker) anywhere you can use an ordinary variable. For 
example: 

PRINT worker).person.namel) 

PRINT "Weekly salary approximately";worker).person.salary/52 

This will work even if the record string is shorter than the record structure, and therefore 
doesn't cover the required field. If this field is numeric the value will be given as 0; if it is a 
string, then as much as possible of the string will be given. 

The record structure can be applied to any number of different strings. You can even apply 
different record structures to the same string. 


2.4.3 Storage classes and memory usage 

When you define an array or record, you reserve space to store the value for each element or 
field. Each clement normally uses the same amount of space as the equivalent simple 
numeric or string variable. Simple numeric variables use 8 bytes each. Simple string 
variables use a minimum of 4 bytes each. This means that if you use large arrays or records, 
your program can run out of memory quite quickly. 

To help you avoid running out of space, you can specify a storage class for an array or field 
when you define it; this restricts the range of values that can be stored in order to limit the 
amount of memory used. In an array all the elements have the same storage class; in a record, 
different fields can have different storage classes. 

Is 


_ 
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The classes available are: 


Class 

Value range 

Memory used per element (bytes) 

BYTE 

-128 to+127 

1 

UBYTE 

0 to +255 

1 

WORD 

-32768 to+32767 

2 

UWORD 

0 to+65535 

2 

INTEGER 

-2147483648 to +2147483647 

4 

IEEE4 

ilO* 38 

4 

IEEE8 

±10 ±3 °* 

8 

FIXED numeric-expression (used for strings) 

the specified numeric-expression of bytes 


IEEE4 and IEEE8 force the number to be stored in the IEEE standard format for 4- and 8- 
byte floating point numbers respectively. This is useful for transferring disk files of numeric 
data from one program to another (not necessarily BASIC 2 Plus). In addition, IEEE4 stores 
floating point numbers in half the space of BASIC 2 Plus's default (4 bytes instead of 8); 
IEEE8 (when used to define the storage class of a record field) increases the range of possible 
binary values from tlO 1200 ! othc full ±10 t3< *. 

Fixed length string items, defined using the keyword FIXED can store strings up to the 
number of characters specified. Attempting to assign a longer string will not cause an error, it 
simply assigns as many characters as arc allowed. Assigning a shorter siring will fill the 
remainder of the string item with trailing nulls. 

When using a fixed length string, all characters after and including the first null character will 
be discarded, so it will behave almost like an ordinary suing variable. To assign it complete 
with trailing nulls, use the function WHOLES: 


string-general-variable = WHOLES ( fixed-length-string) 



WHOLES 

Use 

WHOLES is a function which returns the whole of a fixed-length string. 

Syntax 

WHOLES (.argument) ! 

where 

argument is a string-expression 

Description 

Normally when an expression evaluates to a fixed-length string the final result 
excludes the first null character and all following characters. With WHOLES if 
argument evaluates to a fixed-length string the whole value is returned, as a normal 
string. So WHOLES converts the whole of a fixed-length string to an ordinary string 
(so that it can be assigned to an ordinary string, for example). 
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Normally, the numeric storage classes given above store values according to the normal 
conventions for IBM compatible machines, namely, the low order byte holds the least 
significant byte of the stored number. 

But sometimes it is convenient to represent numbers so that lexicographical ordering of the 
representation corresponds to the natural ordering of the numbers. BASIC 2 Plus enables you 
to do this by following certain storage classes with KEY, for example UWORD KEY, or 
INTEGER KEY. This is most useful when using a record to construct a key value for a keyed 
file (sec Chapter 13) and the the key has numeric components. 

When the storage class contains the word KEY, BASIC 2 Plus stores numbers with the most 
significant byte of the number in the low order byte of memory. As well as that, the most 
significant bit is changed from the normal 2's complement representation, so that positive 
numbers will have the most significant bit set to 1, and non-negative numbers have most 
significant bit zero. This has the effect described above, namely that representations of 
'lower' integers (ie. nearer minus infinity) occur before representations of 'greater' integers in 
the natural lexicographical order. 


KEY can beappended to storage classes BYTE, UBYTE, WORD, UWORD, and INTEGER. 
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This chapter describes the way in which BASIC 2 Plus handles numbers and numeric 
functions. 

It begins with an introduction to the different 'types of arithmetic' (simple. Boolean, and 
bitwise) and the different operators which are appropriate in each case. 

The heart of the chapter is in Section 3.2, Expressions and Operator Precedence. This defines 
'expression' formally (it was deliberately left vague in Chapter 2) and in making the 
definition rigorous it explains the precedence of the various operators. 


The many numeric functions which are available ready-made in BASIC 2 Plus are described 
in Section 3.3. 



Finally there is a detailed discussion of problems which can arise because of the way floating 
point calculations arc carried out 


-h 3.1 Arithmetic and Operators 

! 

Three fundamental types of arithmetic are covered here: 



simple arithmetic, in which numeric values are added, subtracted etc. 
Boolean arithmetic, in which the result is either true or false 



• bitwise arithmetic, in which numbers are manipulated on a level of individual bits 

Simple arithmetic 

Simple arithmetic calculations employ the following operators: 

+ add 

subtract 
* multiply 

/ divide 

\ integer divide 

MOD take remainder after integer division 

A raise to a power 















Typical expressions using these are: 

cost * vat.rate 

total 1 + total 2 + total 3 

balance - payments + receipts + interest 

+ or - may also be used as 'unary operators'. Unary operators precede their operand: unary + 
has no effect on the value of the operand, but unary - reverses its sign. 

The integer division operator \ rounds divisor and dividend to integer, performs the division, 
then truncates the result to integer. (How BASIC 2 Plus rounds and truncates is covered in 
Section 3.3, where we look at specific functions that are available to carry out this action. The 
actions described here are identical to those of the functions CINT and TRUNC respectively, 
andjc\y islhesameasTRUNC(CINTU)/(CINT(y)).) 

The MOD operator rounds divisor and dividend to integer and yields the remainder resulting 
from their division. Thus: 

7.1 MOD 3.3 

is evaluated as 

7 MOD 3 
= 1 

xMODyisthesameasCINT(x) - ((jc\y)*CINT(y)).SpecificalIy,thismcansthat;cMODy 
has the same sign as x, irrespective of the sign of y. 

The exponentiation operator A raises the value to its left to the power of the value to its right. 
For example: 

2 * 4 

is the same as 
2 * 2 * 2 * 2 

Note that the power used with A may be a fraction or negative. For example: 

2 A 0.5 

produces the square root of 2; 

2 a - 4 

produces 

1/(2 * 2 * 2 * 2 ) 










Boolean arithmetic 
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Boolean arithmetic is named after the pioneer of symbolic logic George Boole; it employs 
operators which evaluate whether a condition is 'true' or 'false' and return the values -1 and 0 
respectively. Boolean expressions chiefly appear in conditional statements and in loops 
where they express logical relationships which are used to control the flow of the program 
(see Chapter 5 'Flow of Control'). 

If you wish, you can assign the results of Boolean expressions to numeric variables and then 
use these within your program. Alternatively, you can usc-1 and 0 in control structures as if 
they represented 'true' and 'false'. 

If you use another value (ie. not -1 or 0) in a control structure, BASIC 2 Plus will interpret it 
as 'true'. Note, however, that only -1 will be converted from 'true' to 'false' by the NOT 
operator. 

BASIC 2 Plus's relational operators are: 

< is less than 

<= or -< is less than or equal to 

= is equal to 

>=or => is greater than or equal to 

> is greater than 

<> is not equal to 

For example, x<y: this gives the result -1 ('true') if x is less than y, but 0 ('false*) if x is not less 
than y. 

Boolean expressions can be combined using the logical operators NOT, AND, OR and XOR, often 
in combination with relational operators. 

NOT is a unary operator which inverts the result of a Boolean expression, changing true to 
false and false to true. 

The other three operators compare two Boolean expressions. The following truth table 
summarises their action: 


false op false false 

false op true false 

true op false false 

true op true true 


AND 


OR 

false 

true 

true 

true 


XOR 

false 


true 

true 

false 
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FALSE & OFF 

Use 

FALSE and OFF are functions which always returns 0, the value which BASIC 2 
Plus deems to represent the Boolean value ‘false’. 

Syntax 

FALSE 


OFF 


TRUE & ON 

Use 

TRUE and ON are functions which always returns -1. 

Syntax 

TRUE 


ON 

Note 

Basic 2 Plus deems all non-zero values to represent the Boolean value True. 

These functions return the value -1 because the representation of this value as 
a 32 bit integer has all 32 bits equal to 1. Zero, which is deemed to represent 
the Boolean value false, has all 32 bits equal to 0 (surprise !). This is relevant to 
the operators NOT, AND, OR and XOR, which operate "bit-wise" on 32 bit integer 
values. 


Bitwise arithmetic 


Bitwise arithmetic is a rather specialised form of arithmetic that manipulates numeric 
information on the level of individual bits. It can be applied to integer-expressions, which it 
interprets according to the 32-bit 2's complement convention. 

The bitwise operators are the logical operators NOT, AND, OR and XOR used in Boolean 
arithmetic. Here, NOT inverts each bitin the following value. In terms of bits, NOT 1 is 0, NOT 
0 is 1. The other operators all operate on two values, immediately preceding and following 
them. Their effects are as follows. 

• ANO sets bits to 1 in the result only if they were 1 in both values. 

• OR sets bits to 1 in the result if they were 1 in either or both values. 

• XOR sets bits to 1 in the result if they were 1 in exactly one of the values. 

The actions arc entirely consistent with the integers -1 and 0 being used to represent 'true' and 
'false'. In particular, NOT(-1) is 0 and N0T( 0) is -1. 


/ 
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3.2 Expressions and Operator Precedence 





An expression is formed by combining operators with 'primaries' which include constants, 
variables, array elements, functions, as well as sub-expressions enclosed within parentheses. 
An expression is evaluated to yield a single result when the statement containing it is obeyed. 

(Primaries can include substring selectors and a record field selectors. Records and fields 
were discussed in the previous chapter; substrings are discussed in the next.) 

A typical expression consists of alternating operators and primaries, for example: 

2 + 4 A 3 * SQR (result) 



It is not essential to put spaces between operators and primaries except when it is obviously 
necessary to separate reserved words from each other or from user-defined names. However, 
it is good programming style to do so, as it makes mistakes less likely, and makes programs 
more readable. 

Expressions are evaluated in stages, working always from left to right A specific 
consequence of this is that user-defined functions are always evaluated strictly in the order 
they appear, from left to right through the expression, irrespective of any brackets or 
operators. This can be important when working out the consequences of side-effects of these 
functions. (However, it is bad style to write expressions which take different values 
dependent on the order of evaluation.) 

The order in which the elements of the expression are combined is defined by the precedence 
of the operators. The parts of the expression including operators in the highest precedence 
group are evaluated first. These intermediate results are then combined with operators with 
the next highest precedence, and the results are evaluated. This process continues until the 
lowest priority operators have been combined with their operands, and the final result can be 
returned. 

The order of evaluation is further modified by grouping parts of the expression between 
parentheses (round brackets). Any section of an expression which is between parentheses is 
evaluated fully before it is combined with any part of the expression outside the brackets. 

Brackets can be nested, in which case the innermost level is evaluated first and further 
evaluation precedes outwards. For an example of this, see under 'Order of Evaluation' below. 

Note that each expression is completely evaluated before using the result, so that an 
instruction such as: 

cost = cost * 2 

will not cause any problems (this example simply doubles the previous value of cost). 
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Order of evaluation 

As described above, the order in which any expression is evaluated is defined by 'operator 
precedence'. 

The operators described in this section are classified into groups according to their 
precedence. 

Precedence group Operators 

1 (highest) 

2 unary*, unary- 

3 * / \ noo 

4(lowest) ♦ - 

For example, consider 
4*3-5 A 2 + 3 

As A has the highest precedence, 5 A 2 is evaluated first, producing: 

4 * 3 - 25 + 3 

Next comes *, so 4 * 3 is evaluated next, producing: 

12-25+3 

As + and - have the same precedence, their parts are evaluated left to right, producing: 

-13 + 3 
then: 

-10 

So the result is -10. 

Note specifically that A has a higher precedence than unary - and+. -2 A 2 is -4, not+4. 

If you need to make the order of evaluation clear or you want to force a different order, use 
brackets to break the expression up into sub-expressions. The inside of each bracket will then 
be evaluated independently to yield a result which will be used in the rest of the expression. 
For example: 

4 * (3 - 5) A 2 + 3 
will be evaluated as: 

4 * (-2) A 2 + 3 













I 
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Relational operators have equal precedence, but lower precedence than arithmetic operators. 
Thus, an expression such as 

4 >= 5 + 2 

is evaluated as 

4 >= 7 

ie. false, or 0. Compare this with the expression 
( 4 >- 5 ) + 2 

in which the 4 >= 5 is evaluated as'false', ie. 0, and so the whole expression evaluates to 2. 
However, NOT has higher priority than everything except A . 

The logical operators have the lowest precedence of all, less than relational or arithmetic 
operators. The full precedence table is therefore as follows: 



Precedence group 

1 (highest) 

2 

3 

4 

5 

6 

7 

8 

9 (lowest) 


Operators 

A 

unary +, unary- 

*, /, \, MOD 

+,* 

<, <=, =<, =, <>, >=, =>, > 

NOT 

AND 

OR 

XOR 


Numeric functions 


Functions return a result derived from one or more expressions supplied in brackets after the 
name. Most have a single argument, so they are used thus: 

name( expression) 

The ones described here are all numeric functions, ie. they return a numeric result. (String 
functions are described in the next chapter.) A numeric function can be used anywhere that a 
numeric value is needed, for example to assign to a numeric variable, in a PRI NT command, in 
numeric expressions or as an argument for another function. 



A range of commonly required functions is supplied within BASIC 2 Plus. You can define 
other functions yourself: see the section on User-defined functions' in Chapter 6. 
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The functions described here deal with: 

• logarithm and powers 

• random numbers 

• maxima and minima 

• rounding and truncation 

• special values (eg. the largest representable number) 

• signs and absolute values 

• handling the time and the date returned by the operating system 

• trigonometry 

Logarithms and Powers 

As described previously, to raise a number to a power, use the exponentiation operator, A . For 
example, to print 7 to the 4.4th power 

PRINT 7M.4 

To find the nth root of a numeric value, use of the fact that it this is the 1/nth power of that 
value. For example, to find the cube root of y: 

root3 = y A (1/3) 

To find the square root of a numeric value, use the function SQR. This takes a single numeric 
argument, which must not be negative. For example: 

a - SQR(b * b + c * c) 

There are three logarithmic functions. To calculate the natural logarithm of n, use L0G( n). 
To calculate the logarithm to base 10 of n, use LOG 10 (n). To calculate the logarithm to 
base 2 of n, use L0G2 ( n). n must be greater than zero. 

To raise the real number e (2.71828...) to the power n, use EXP(/7). n should be in the 
approximate range-708.39 <n< +709.78 More negative arguments yield 0, more positive 
arguments cause overflow, yielding an error. 
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Use 

EXP 

EXP is the exponentiation function, the inverse of the natural logarithm. 

Syntax 

where 

EXP (argument) 

argument is a numeric-expression. 

Description 

EXP returns e to the power of argument (where e is the base of natural logarithms). 

Use 

LOG 

LOG is a function which returns the logarithm to base e of its argument - the 
natural logarithm. 

Syntax 

where 

LOG ( argument ) 

arguments a numeric-expression, giving a positive, non-zero, value. 

Use 

LOG2 

L0G2 is a function which returns the logarithm to base 2 of its argument. 

Syntax 

where 

L0G2 (argument) 

argument is a numeric-expression, giving a positive,; non-zero, value. 

Use 

LOGIO 

L0G10 is a function which returns the logarithm to base 10 of its argument. 

Syntax 

where 

LOGIO (.argument) 

argument is a numeric-expression, giving a positive, non-zero, value. ' 

Use 

SQR 

SQR is a function which returns the (positive) square root of its argument. 

Syntax 

where 

SQR (argument) 

argument is a numeric-expression, returning a positive, or zero value. 
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Random numbers are obtained using the function RND, as follows. 

RND without an argument returns a fraction from 0 to 1. (0 is a possible value; 1 is not.) 

RND with an integer expression i as its argument returns an integer in the range 1 to /. / must 
lie in the range 1 < / < 65535. 

BASIC 2 Plus generates 'pseudo-random' numbers - numbers in a sequence where each 
depends on the previous number. Starting from a given value, this sequence is always the 
same. 

To restart the sequence, use the command RANDOMIZE. This sets a new initial or 'seed' for the 
sequence. If followed by a numeric expression it uses this value as the new seed. By 
specifying the same seed, you can ensure that exactly the same sequence of random numbers 
will be generated. This is particularly useful when testing programs. 

If used without a parameter, BASIC 2 Plus uses a seed based on the machine's internal clock. 

Note that RANDOMISE is not an acceptable spelling of the word. 

Maxima and minima 

To pick out the highest value from a list, use MAX; to pick out the lowest, use MIN. These each 
take a variable number of numeric arguments. For example: 

PRINT "The winning score is MAX(mark(1),mark(2),mark(3),mark(4)) 


Highest is taken to mean 'most positive, while lowest is taken to mean 'most negative'. So that 
if the arguments are negative, MAX returns the least negative one. 



MAX 

Use 

MAX is a function which returns the value of its largest argument. 

Syntax 

MA X( argument, argument(, argument )...) 

where 

each argument is a numeric-expression. 

Description 

MAX evaluates each argument in turn, returning the value of the largest (the value 
nearest positive infinity). Note that MAX may take any number of arguments, 
provided there are at least two. provided there are at least two. 
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Use 

RND 

RND is a function which returns a pseudo-random number. 

Syntax 

where 

RND [(argument)] 

argument is an integer-expression, giving a value in the range 1 .. 65535. 

Description 

RND without an argument returns the next pseudo-random number in a sequence 
of pseudo-random numbers uniformly distributed in the range 0..1 (where 0 is a 
possible value, but 1 is not). 

RND with an argument returns the next pseudo-random number in a sequence of 
integer pseudo-random numbers uniformly distributed in the range 1 .. argument 
(where both 1 and argument are possible values). 

RANDOMIZE 

Use 

RANDOMIZE is used to set the seed for BASIC 2 Plus's pseudo-random number 
generator. 

Syntax 

where 

RANDOMIZE [seed-value] 
seed-value is a numeric-expression. 

Description 

RANDOMIZE sets the initial value for the sequence of random numbers generated 
by RND. This means that if RANDOMIZE is called on separate occasions with the 
same value of seed-value , thereafter RND will produce identical sequences of 
random numbers. 

If seed-value is omitted, RANDOMIZE sets an initial value based on the time held by 
the computer's internal clock at the time. 


Use 

MIN 

MIN is a function which returns the value of its smallest argument. 

Syntax 

where 

MIN ( argument, argument[, argument]...) 
each argument is a numeric-expression. 

Description 

MIN evaluates each argument in turn, returning the value of the smallest (the value 
nearest negative infinity). Note that MIN may take any number of arguments, 
provided there are at least two. 











Rounding and truncation 


When a function requires an integer value, any numeric expression given as an argument is 
automatically converted. There arc also functions to convert a numeric value to integer 
explicitly. These are used to force a conversion where one would not normally take place, 
or to produce a conversion other than that which would occur. These functions are 
FLOOR. CEILING. ROUND. CINT. TRUNC. INT. CEIL, and FIX. 

FLOOR is used to round a number to the next smaller (more negative) whole number. For 
example, FL00R(3.9) will produce 3, while FL00R(-3.9) will produce -4. (An alternative 
name for FLOOR is INT.) 




CEILING is used to round a number to the next larger (more positive) whole number. For 
example, CEILING(3.9) will produce 4, while CEILING(-3.9) will produce -3. (An 
alternative name for CEI LI NG is CEIL.) ““ 


ROUND {number,places) rounds a number to a given number of places. For example, 
R0UND(3.335,2) will produce 3.34 while R0UND(-3.335,2) will produce -3.34. If omitted, 
places is taken as 0, so ROUND(3.335) produces 3. If places is negative, it is taken as the 
number of figures to round to on the left of the decimal place; for example, -r^. 
R0UND(123456.7,-4) will produce 120000. !X 


CINT rounds to an integer in the range -2,147,483,648 to +2,147,483,647. CINT(f) is 
similar to R0UND(/,0).except that it raises an error if its argument cannot be rounded to an /]*, 
integer in the above range. 


TRUNC rounds a number by simply losing the fractional part. For example, TRUNC(3.9) will 
produce 3, while TRUNC(-3.9) will produce -3. (An alternative name for TRUNC is FIX.) 



Finally, to determine the fractional part of a number, use the function FRAC. For example: 
c - FRAC(n) 

FRAC(/7) is equivalent to o-TRUNC(n). 



CINT 

Use 

CI NT is a function which returns the value of its argument rounded to an integer. 
Rounding is towards the nearest integer, with halves being rounded away from 
zero. The result must be in the range -2147483648..+2147483647. 

Syntax 

CI NT ( argument) 

where 

argument is a numeric-expression. 
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CEILING & CEIL 


Use 

These functions return the value of their argument rounded to an integer. 

Rounding is upwards, that is, towards plus infinity. 

Syntax 

CEIlING(argumenf) 



FLOOR & INT 


Use 

These functions return the value of their argument rounded to an integer. 

Rounding is downwards, that is, towards minus infinity. 

Syntax 

FLOOR (argument) 

I NT ( argument) 

where 

argument is a numeric-expression. 



FRAC 


Use 

FRAC is a function which returns the fraction part of the value of its argument. 

Syntax 

FRAC( argument) 

where 

argument is a numeric-expression. 



ROUND 


Use 

ROUND is function which returns the value of its argument rounded to a specific 
number of decimal places. 

Syntax 

ROUND (.argument!, rounding]) 

where 

argument is a numeric-expression and rounding is an integer-expression. 1 

Description 

ROUND returns the value of argument rounded to rounding decimal places. If the 
rounding is omitted 0 is assumed. In terms of other BASIC 2 Plus functions ; 

R0UND(x, n) is:SGN(x) * TRUNC((ABS(X) * (10 A n)) + 0.5)/(10 A n) 



TRUNC & FIX 


Use 

These are functions which return the value of their argument rounded to an integer. 
Rounding is towards zero. 

Syntax 

TRUNC (argument) 

FI argument) 

where 

argument is a numeric-expression. 
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Special values 


The special values you may want to use in your programs are: 

• the minimum and maximum representable numbers 

• the value of n. 

These values are returned by the functions MAXNUM and PI respectively. Note that neither of 
these functions takes any parameters. 

The smallest strictly positive number which can be represented in BASIC 2 Plus is given by 
EPS (0). This is a special case of the EPS function, which is explained in detail in Section 3.4 
'Speed and Accuracy in Calculations'. 


Signs 

To determine the sign of a number (expression, variable), use SGN. This returns 0 if the value 
is 0, -1 if it is less than zero, +1 if it is greater than zero. To ensure that a numeric value is 
positive, use ABS. This converts a negative or positive number to a positive number of the 
same magnitude: 

ABS(va lue) 



ABS 

Use 

ABS is a function which returns the absolute value of its argument. 

Syntax 

ABS (argument) 

where 

argument is a numeric-expression. 


SGN 

Use 

SGN is a function which returns the sign of the value of its argument. 

Syntax 

SGN (.argument) 

where 

argument is a numeric-expression. 

Description 

SGN returns -1,0 or +1 indicating that the value of argument is less than zero, zero 
or greater than zero, respectively. 
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MAXNUM 

Use MAXNUM is a function which returns the largest representable number. 

Syntax MAXNUM ; 

PI 

Use PI is a function which returns the representable value closest to the mathematical 
constant n. 

Syntax PI 


Time and date 

The functions TIME, TIMER and DATE read the time and date from the computer's clock. 

TIME returns an integer which is the time in hundredths of a second since midnight It has no 
arguments. 

Note that on some computers the clock's resolution is not as good as a hundredth of a 
second. 

By way of example, to convert the time as returned by the function TIME (in hundredths of a 
second since midnight) into hours, minutes and seconds: 

total.seconds - FLOOR(TIME/100) 
hours - total_seconds\3600 
minutes - (total ..seconds MOD 3600)\60 
seconds = total .seconds MOD 60 

TIMER produces the number of seconds since midnight. Note that TIME always returns an 
integer value; this is not necessarily true of TIMER. 

DATE produces an integer which is the date, in days since 31st December 1899 (1 = Monday 
1st January 1900). Without arguments, DATE gives the current date, with an argument 
DATE ( string) gives the specified date string as the number of days since 31st December 1899. 
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The form of the date string expected depends on the country code of your computer' 
operating system. It can be altered using: 

OPTION DATE form/, separator] 

where form and the date format arc as follows: 


form 

Format 

form 

Format 

0 

mm/dd/yy 

4 

mm/dd/yyyy 

1 

dd/mm/yy 

5 

dd/mm/yyyy 

2 

yy:mm:dd 

6 

yyyy:mm:dd 

3 

yymmdd 

7 

yyyymmdd 


If the separator is not given, then the separators above arc used. If it is given, then it must be a 
string of which the first character is used. The string may be null, in whch case no separator is 
given and all dates arc assumed to have leading zeros before single digits: 030939. 

To convert dates from a number to a string format, or to generate the current date as a string, 
use the function DATES, described in the next chapter. 



TIME 

Use 

TIME is a function which returns the number of hundredths of a second which 
have elapsed since midnight, to the nearest hundredth. 

Syntax 

TIME 

Note 

TIME always returns an integer. This value is derived from the system clock. 

Note that the unit of time used by the the system clock limits the precision to 
which time may be measured, and, in particular, that this unit may be greater than 
a hundredth of a second 


TIMER 

Use 

TIMER is a function which gives the number of seconds which have elapsed since 
midnight. 

Syntax 

TIMER 

Note 

TIMER returns the representable value closest to the time given by the system 
clock. Note that the unit of time used by the the system clock limits the precision 
to which time may be measured 
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DATE 

Use DATE is a (unction which converts a date in the form of a string to a date as a 
number of days since 31st December 1899. 

Syntax 0 AT E](, argument)] 
where argument is a string-expression. 

Description DATE returns the number of days since 31st December 1899 up to and including 
the date expressed in the string argument, (ie. DATE( 1/1/00 ) is 1.) 

argument must give the date in conventional form. This will depend on the country 
code of the computer's operating system, but for the United Kingdom it consists of 
the day, the month and the year, in that order, each represented by one or two 
digits, and separated from each other by slashes, for example 13/3/56. 

Conventional form for dates can be changed using the OPTION DATE statement. 

There is some tolerance in the way the date may be represented, but if it is in an 
incorrect form, DATE returns 0; no error is raised in this case. 

If argument is omitted, the current date is returned. 

DATE is the inverse function of DATE$. 


Converting the string representation of a number to a number 

Numbers stored as strings can be converted to numeric form for use in calculations by using 
the function VAL: 

number = VAL ( string-expression ) 

The string can either be a siring of decimal digits, or it can be a binary string (&Xn) or a 
hexadecimal string (&n). It can include leading or trailing spaces. VAL in fact carries out the 
conversion in the same way as INPUT (sec Chapter 10). 

For example: 

PRINT VAL(" &FF ") 

255 









VAL 

Use VAL converts the string representation of a number to its numeric value. 

Syntax VA L ( argument) 
where argument is a string-expression. 

VAL interprets its argument as a number, and returns its numeric value, argument 
can be in any of the standard forms: it can start with & or AX, or it can be in 
scientific format, with a scaling factor. 

argument may contain embedded underline characters and if it represents a 
decimal number it can contain embedded spaces. These extra characters are 
ignored, as are all leading and trailing spaces. 

See also: STR* 


Trigonometry 

There are three trigonometric functions, for converting angles into cosines, sines and 
tangents: COS, SIN and TAN. Each takes a single numeric argument, in brackets. For example: 

opposite - adjacent*TAN(theta) 

COS, S IN, and TAN will reject arguments much bigger than 32750 * it. 

There are also three functions to convert cosines, sines and tangents back into angles: ACOS. 
AS IN, ATAN. For example: 

theta - ATAN(opposite/adjacent) 

(ATAN can also be spelled ATN.) 

There is also a function provided to simplify tasks like converting cartesian co-ordinates to 
polar co-ordinates: ATAN 2. This takes two arguments: 

polar_angle - ATAN2(x,y) 

where x and y are the cartesian co-ordinates. The angle returned is in the range -n to +rt 
radians (-180 to +180 degrees), correctly interpreting negative arguments and coping with an 
x value of zero. With x and y both zero, ATAN2 returns zero. 



>4 











Chapter 3: Working with Numbers 



COS 

Use 

COS is a function which returns the cosine of its argument. 

Syntax 

COS (.argument) 

where 

argument is a numeric-expression. 

Description 

COS returns the cosine of argument which is assumed to be in radians unless this 
has been changed with OPTI ON DEGREES. The value of argument is restricted to 
the approximate range ±32750 * n. 


SIN 

Use 

SIN is a function which returns the sine of its argument. 

Syntax 

SIN (argument) 

where 

argument is a numeric-expression. 

Description 

SIN returns the sine of argument which is assumed to be in radians unless this has 
been changed with OPTION DEGREES. The value of argument is restricted to the 
approximate range ±32750 * 7t. 


ACOS 

Use 

ACOS is a function which returns the angle whose cosine takes the given value. 

Syntax 

ACOS (argument) 

where 

argument is a numeric-expression, giving a value in the range -1..+1. 

Description 

ACOS returns the angle in the range 0..?t whose cosine is equal to argument . The 
value returned is in radians by default, though this can be changed with OPTION 
DEGREES. 


ASIN 

Use 

AS IN is a function which returns the angle whose sine takes the given value. 

Syntax 

AS I N( argument) 

where 

argument is a numeric-expression, giving a value in the range 

Description 

ASIN returns the angle in the range -jt/2..+x/2 whose sine is equal to argument. 

The value returned is in radians by default, though this can be changed with 
OPTION DEGREES. 


















TAN 

Use 

TAN is a function which returns the tangent of its argument. 

Syntax 

TAN (argument) 

where 

argument is a numeric-expression. 

Description 

TAN returns the tangent of argument which is assumed to be in radians unless this 
has been changed with OPTION DEGREES. 


The value of argument is restricted to the approximate range ±32750 * tc. 


ATAN2 

Use 

ATAN2 is a function which returns the angle between the x axis and the line from 
the origin to the given point. 

Syntax 

ATAN2( x, y) 

where 

x and y are numeric-expressions. 

Description 

ATAN2 returns an angle in the range -n..+it. If both x and y are zero the value 
returned is zero. The value returned is in radians by default, though this can be 
changed with OPTION DEGREES. 


ATAN & ATN 

Use 

These functions return the angle whose tangent takes the given value. 

Syntax 

AT AN (argument) 

ATN (argument) 

where 

argument is a numeric-expression. 

Description 

ATAN and ATN return the angle in the range -tc/2..+jc/2 whose tangent is equal to 
argument. The value returned is in radians by default, though this can be changed 
with OPTION DEGREES. 
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BASIC 2 Plus normally works with angles expressed as radians. 

To convert degrees to radians, use the function RAD: 
theta2 - RAD(theta) 

To convert radians to degrees, use the function DEG: 
theta = DEG(theta2) 

BASIC 2 Plus normally works with angles expressed in radians, but to switch to using 
degrees, use: 

OPTION DEGREES 

To switch back to radians, use: 

OPTION RADIANS 

Note that this affects the angles used throughout programs, with the exception of text written 
at an angle, which is always specified using degrees. 



DEG 

Use 

DEG is a function to converts angles in radians to degrees. 

Syntax 

DEG( argument) 

where 

arguments a numeric-expression. 

Description 

DEG returns the value of argument multiplied by 180/re. 

DEG and RAD are each other’s inverse. 

RAD 

Use 

RAD is a function to converts angles in degrees to radians. 

Syntax 

RAD (argument) 

where 

argument is a numeric-expression. 

Description 

RAD returns the value of argument multiplied by re/180. 

RAD and DEG are each other's inverse. 
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3.4 Speed and Accuracy in numeric calculations 

BASIC 2 Plus has only one type of numeric variable, and it occupies 8 bytes of memory. You 
never have to specify whether a number is to be stored as integer or floating point, single or 
double precision, as in some BASICs; BASIC 2 Plus chooses the most appropriate format to 
store the number in the 8 bytes, and it handles any conversions to different formats which 
may be necessary when arithmetic is carried out. 

However, sometimes it is important to understand how things work, especially when dealing 
with large numbers or small fractions, and when writing numbers to a disc file. This section 
of the manual explains how numbers are stored, describes the choice between binary 
precision and decimal precision, and discusses possible errors which can be introduced 
through the use of floating point numbers. 



- 




Integer and Floating Point Arithmetic 

If BASIC 2 Plus can work in integers, it does. Integer arithmetic is fast and entirely accurate, 
and the range of numbers which can be stored (-2,147,483,648 to +2,147,483,647) is wide 
enough to allow financial calculations up to billions of pounds to be carried out accurate to 
the nearest pound. 


Integers are stored in 32-bit 2's complement format 

Numbers outside this range and numbers with a fractional part arc stored in floating point 
format. This has a much wider range: ±10 ±30S ; in other words the most positive and most 
negative numbers representable are roughly +10°“ and -10* 308 and the numbers with the 
smallest magnitude which are distinct from zero are roughly +10" 30 * and -Kf 30 *. However, 
floating point arithmetic is slower than integer arithmetic, and can introduce errors, as we 
shall sec. 


2 - 
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Binary and Decimal Arithmetic 

BASIC 2 Plus offers you the option of working in binary or decimal arithmetic. Binary 
arithmetic means that floating point numbers are converted from decimal to binary 
representation before they are stored. All the arithmetic performed on them is done in binary, 
and the results are converted back to base 10 before they are output. Unfortunately the 
conversions cannot be exact when fractions are involved - the error introduced is tiny, and 
for many applications immaterial. (See below for more detail.) 
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Decimal arithmetic means that numbers are stored as they are input: as decimal digits.' 
Arithmetic is all done in decimal, and there is no need to convert the results before they are 
output Decimal is slower than binary, but, because there is no conversion, decimal fractions 
are input and output exactly (for numbers with up to 15 significant digits). This is most useful 
when dealing with money values where it is convenient to have exact decimal fractions. 

Decimal arithmetic is specified by including the statement 
OPTION ARITHMETIC DECIMAL 

anywhere in your program. The corresponding statement for binary arithmetic is 
OPTION ARITHMETIC NATIVE 

A program runs entirely in binary or in decimal; you can’t over change in the middle. So it is 
an error to include both the above statements. 

You might think there could be confusion when floating point numbers are written to a file. 
What happens if the file is written by a program using binary arithmetic, but read back by a 
program using decimal arithmetic? The answer is that BASIC 2 Plus writes to fields in 
records in a special 8-byte format which enables it to distinguish binary from decimal when 
the number is read back in. When binary arithmetic is in use the form used is similar to the 
IEEE standard for double length floating point numbers, but with reduced range: instead of 
HO 1308 the range is about llO* 200 . (If when using binary arithmetic you need to store numbers 
with the full range, you should specify a storage class of IEEE8, which forces BASIC 2 Plus 
to use the standard 8-byte binary representation of floating point numbers.) When decimal 
arithmetic is in use the form used allows the full range. 

Impossible Calculations 

Certain calculations which it is possible to specify using the syntax of BASIC 2 Plus are 
impossible for certain values of the operands. These impossible calculations come into three 
categories: overflow, underflow, and invalid calculations. 


Overflow 


Overflow is when the result of a calculation is too big for BASIC 2 Plus to store: in other 
words, it falls outside the range 10 t3 °*. Arithmetic overflow is treated as an error - so, unless 
other arrangements have been made, execution of the program stops and an alert box is 
displayed telling you about the overflow. 
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Underflow 


Underflow is when the result of a calculation is so small that BASIC 2 Plus cannot represent 
it without rounding it to zero. Normally, that is exactly what happens, and the calculation 
proceeds with zero instead of the true value. 

However you can choose to have underflow treated as an error by including the command 
OPTION UNDERFLOW 
anywhere in your program. 


Invalid Calculations 


Invalid calculations arc those for which there is no answer, such as dividing zero by zero, or 
taking the square root of a negative number. Invalid calculations cause an error, in the 
usual way. 

Floating Point Arithmetic Errors 

Floating point numbers are stored in two parts, a 'significand' and an 'exponent'. When binary 
precision arithmetic is selected, the significand is a binary fraction and the exponent gives the 
power of 2 to multiply the significand by, to produce the actual value. When decimal 
precision arithmetic is selected, the significand is a decimal fraction and the exponent gives 
the power of 10 by which the significand has to be multiplied. 

This is a very powerful system for storing numbers but there are two problems. 


Conversion Error 


The first problem only affects binary precision and it is that many (indeed most) decimal 
fractions simply do not have exact representations in binary. The decimal fraction 0.1, for 
example, is the recurring binary fraction 0.000110011001100110011... When such a 
decimal fraction is converted to binary it is rounded to the nearest representable value. While 
the result is precise to within the limits given for the form of number, it is not exactly equal to 
the original fraction. 

A small error is therefore introduced whenever a number is stored. In BASIC 2 Plus, binary 
precision numbers have a significand of 53 binary digits, so on conversion every number is 
rounded to fit in these 53 digits. This can lead to a relative error smaller than ±2 -33 (or 
about 1.1E-16). 
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When fractional values are printed, binary numbers are converted to decimal, which 
generally involves rounding to at most 15 significant decimal digits. The inexactness of the 
representation may, therefore, be hidden. Furthermore, values which are actually different 
will produce the same result when printed - the difference may only come to light if the 
values are compared or subtracted. 

You should understand that this is a consequence of the use of binary floating point It is not 
a fault in BASIC 2 Plus’s arithmetic - all binary floating point systems work this way. 

Rounding Error 

The second problem affects both binary and decimal precision arithmetic. Both the 
significand and the exponent have a restricted number of digits. The effect of this in the case 
of the exponent is to limit the range of values which can be represented. In the case of the 
significand, it means that the value held is not exact but is rounded to the nearest value 
possible in the digits available. In other words, the number of digits in the significand dictates 
the precision to which any number can be held. 

Compounding Rounding Errors 

Every arithmetic operation compounds the error. The analysis of the errors produced in 
sequences of floating-point calculations is highly complicated. However, it is possible to give 
a flavour of what happens. 

When you multiply any two 'approximate' numbers, it is not hard to show that the relative 
errors in the two individual numbers effectively add together. With floating point 
representation, you gel a further effect in that the multiplication produces twice as many 
significant digits as in tbe arguments. So it is necessary to round the result to the number of 
digits available for the significand. In binary precision arithmetic, this can introduce a further 
error of at most ±2" 33 . 

When this error is compounded with conversion error in each of the operands, we see that the 
result may contain an error three times as large as the original errors. Three times ±2' 53 is still 
not a large error, but the error gets larger as you carry out further multiplication. 

The analysis of addition and subtraction is more complicated. Again, there are two problems. 

The first occurs when the two numbers are of different sizes. Then it is necessary to divide 
the significand of the smaller number to make the exponents the same. There are then fewer 
digits representing the smaller number and so the relative error in the smaller value instantly 
becomes larger. 
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EPS function 


This is not a serious problem for a single addition, but can badly affect multiple additions. 
For example: 

total-0 
count-5 

sma11 _num-l.23456789 
large_num-9876.54321 
FOR 1-1 TO count 

total-total+small_nunH-large_num * add these numbers count times 
NEXT 1 

expected - (small_num * count) + (large_num * count) 

PRINT "The relative error is:": (total-expected) / expected 
END 

produces Ihe result -1.47319727E-16, which is small, but visible. 

Furthermore, with increasing difference in the sizes of the arguments the value of the smaller 
approaches the error in the representation of the larger! 

Floating point subtraction of values of similar size can produce still more unpleasant effects. 
The errors may then be large compared to the true result. For example 1.1-1.09999999 gives 
the result 1.00000002E-8, which is has relative error of approximately 1.6E-8 ! 



A measure of the precision of a floating-point value can be obtained by using the function 
EPS: 

result - EPS(x) 

EPS returns what the absolute value of the least significant digit of the argument would be if 
that digit was 1. In binary arithmetic mode this value will be some power of 2; in decimal it 
will be some power of 10. If the aigumcnt is very small the true EPS value may not be 
representable, in which case the smallest representable number is returned. EPS(O) is, 
therefore, the recommended method of establishing the smallest representable value. Note 
that EPS always returns a positive value. 
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Recommendations 

• Scientific and engineering calculations 

Binary floating point is well suited to this sort of calculation, since it is not generally 
necessary for the results to be quoted exactly: an appropriate number of significant figures is 
usually all that is required, and BASIC 2 Plus's arithmetic provides more than enough for 
most applications. 

Complicated numerical algorithms will need to be carefully designed. However, the 
following recommendations should help with simple problems: 

Do not test for equality directly: It is very unlikely that the statement after the THEN in IF x 
= 7.41 THEN ... will ever be executed - unless the value 7.41 is assigned directly to x.The 
alternatives are to round x so that the test takes into account the acceptable margins of error 
for the problem, or to test that x lies in some range suitable to the problem. Another option is 
to use the EPS function to assess how close the value is to the desired value compared to a 
change of 1 in the last significant digit. 


EPS 


Use 


Syntax 

where 


EPS is used to give a measure of the significance of a number, in other words, 
the smallest change in the number which can be meaningfully represented. 

EPS l argument) 

argument is a numeric-expression. 

Description EPS returns the maximum of x-x', x"-x and o where x =argument 

x' = the nearest representable value less than x (or x if x is the smallest 
representable value) 

x" = the nearest representable value greater than x (or x if x is the largest 
representable value), 
o = the smallest representable value. 


Beware of subtracting values of similar size: As explained above, these can produce quite 
badly flawed results, because any errors can be hugely magnified. It may be necessary to 
examine the result of a subtraction, and treat it as zero if its absolute value is less than some 
minimum suitable to the problem (ROUND may be used to do this, as well). 


BASIC 2 Plus: Language Reference 


63 


Working with Numbers 


















Beware of repealed additions: Because each addition can contribute a rounding error to the 
result it is best to use a single addition of a value which is multiplied up. Ifif" 


Beware ofINT and FIX: These functions produce integers from floating point values. They , 
arc very literal minded, for example I NT (1 - EPS(l)) is 0 ! The FIX function iscqually JJJ- 
brutal. The solution, as ever, lies in examining the levels of accuracy required by the problem 
and applying them - for example INT(ROUND(x. 5)) may be suitable for some 
applications. 

Beware of addition and subtraction of values of widely differing sizes: Adding a small 
number to a much laigcr one can lead to loss of significance. < 0 


Financial calculations 

Floating point in general, and binary floating point in particular, are not ideally suited to 
financial calculations. Most financial calculations must be exact. The programmer must, 
therefore, take steps to ensure that the results of operations on money values arc indeed exact. 

The following are recommended: ^r 


Use Decimal precision: Binary precision will introduce conversion error, since numbers 
cannot be represented exactly using binary arithmetic. 


Use ROUND: Where the result of a calculation is a sum of money, then ROUND should be 
used to round to the required number of decimal places (typically 2). For example: 

DIM flguresfl TO 10. 1 TO 10] 

RANDOMIZE 5 

FOR c - 1 TO 10 ' Construct 10x10 array of money values 
FOR r - 1 TO 10 

figuresfe. r] - RND(10 000) / 100 
NEXT r 
NEXT c 

row_grand_total - 0 
FOR c - 1 TO 10 ' Produce row totals 
row_total - 0 
FOR r - 1 TO 10 

row_total - row_total + figuresfe, r] 

NEXT r 

row_grand_total - row_grand_total + row_total 
NEXT c 






FOR r = 1 TO 10 ' Produce column loll IJ 
col_total = 0 
FOR c = 1 TO 10 

col_total - col_total + figures[c, r] 

NEXT c 

col_grand_total = col_grand_total + col_total 
NEXT r 

PRINT col_grand_total - row_grand_total 

PRINT ROUND(col_grand_total. 2) - ROUND!row_grand_total. 2) 

produces two numbers 9.09494702E-13 and 0. This shows how errors can accumulate, even 
when the the difference is minute, but the extra ROUND step ensures that it is actually zero. 

Beware of Rounding: ROUND must be used with care, since it can subtly affect the sums you 
are doing. In the following example five values arc to be discounted by 45%. This is done 
firstly by adding the discounted prices and rounding the result at the end, and secondly by 
rounding each discounted price and summing the rounded values. 

OPTION ARITHMETIC DECIMAL 
discount = 45 
sum_of_rounded = 0 
rounded_sum - 0 
READ count 
FOR i = 1 TO count 
READ full_price 

discounted_price = full_price * ((100 - discount) / 100) 
rounded_sum = rounded_sum + discounted_price 
sum_of_rounded = sum_of_rounded + R0UND(di$counted_price. 2) 

NEXT i 

rounded_sum = R0UND(rounded_sum, 2) 

PRINT rounded_sum: sum_of_rounded 
END 

DATA 5. 90.92, 87.14. 15.84. 21.25. 74.61 

produces the results 159.37 and 159.38. This effect is nothing to do with the floating point 
arithmetic. Both results arc correct, reflecting two different approaches to the problem of 
discounting multiple items. 
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Working with Strings 


This chapter describes the various ways in which strings can be manipulated. These include: 

• combining strings into a single string 

• analysing strings - finding out length; finding out whether they contain particular 
characters or groups of characters 

• picking out sections of a string 

• replacing sections of a string 

• comparing strings 

Different types of string 

A string is a sequence of characters. Like numbers, strings can be explicitly quoted in the 
program code, or they can be held in variables. 

Strings can contain any character with character codes from 0 to 255; you are not just limited 
to the ones you can type. The BASIC 2 Plus function CHR$ can be used to enter any character 
you just need to know the character's code. (See Section 4.4 'Working with character codes' 
for more information about this.) 

A string can contain between 0 and 4096 characters. 

String variables are typically of variable length: ie. the amount of memory they take up 
expands and contracts according to the length of the string they contain. However, to save 
space, string array variables may be given a specific length by use of the keyword FIXED: 
the string is then referred to as 'fixed-length'. String fields in records have to be of fixed 
length. (See 'Storage classes' in Chapter 2 Information handling'.) 

(The exact amout of store taken up by a string variable is 4 bytes if the string contains 
2 or fewer characters, and (4 + FL00R((n+3)/2) * 2) bytes if the string contains mote than 
2 characters.) 
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4.1 Combining and assigning strings 

A string expression can be assigned directly to a general-variable using the standard 
assignment statement: 

string-general-variable - string-expression 
This completely replaces any information currently held. 

Variable-length string items can be assigned strings from 0 to 4096 characters long. 
Attempting to assign a longer string will cause an error. 

If string-expression contains any null characters (ie. characters with GEM code 0), the first null 
and all subsequent characters in the expression are discarded. This can be prevented by using 
the WHOLES function: 

string-general-variable - WHOLES (string-expression) 

You can assign to a string-general-variable without changing the length of the string it holds 
by using the LSET and RSET statements. 

LSET string-general-variable - string-expression 
RSET string-general-variable - string-expression 

LSET assigns string-expression to string-general-variable, truncating it if it is longer than string- 
general-variable, padding it with spaces if shorter. 

RSET assigns string-expression to string-general-variable, truncating it (from the right-hand end) 
if it is longer than string-general-variable, padding it with leading spaces if shorter. 

Combining Strings 

Strings arc combined simply by using the concatenation operator V, which appends one 
string to the end of another. 

The two strings arc combined without any added spaces. If spaces arc required, these have to 
be included explicitly - either in the original strings or as a literal string of spaces: " For 
example: 

firsts - "Chitty " 

second) - "Bang" 

combinedS - firstS+secondS 

PRINT firsts, combinedS. " ", seconds 

Chitty Chitty Bang Bang 






WHOLE$ 

Use WH0LE$ is a function which returns the whole of a fixed-length string. 

Syntax WHO L E$ ( argument) 
where argument is a string-expression 

Description Normally when an expression evaluates to a fixed-length string the final result 
excludes the first null character and all following characters. With WHOLES if 
argument evaluates to a fixed-length string the whole value is returned, as a normal 
string. So WHOLES converts the whole of a fixed-length string to an ordinary string 
(so that it can be assigned to an ordinary string, for example). 

Note that it is not necessary to use WHOLES with field-selectors or in PUT and 
ADDREC. 


LSET 

Use LS ET is used to assign to a string-general-variable without changing the length of the 
string it holds. 

Syntax LS ET string-general-variable = string-expression 

Description string-expression is assigned to string-general-variable , truncating it from the right-hand 
end or appending spaces to the right-hand end as necessary to ensure the length 
of string in string-general-variable is not changed. 


RSET 

Use RS ET is used to assign to a string-general-variable without changing the length of the 
string it holds. 

Syntax RSET string-general-variable = string-expression 

Description string-expression is assigned to string-general-variable . truncating it from the right-hand 
end or appending spaces to the left-hand end as necessary to ensure the length 
of string held by string-general-variable is not changed. 
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Stored strings may well have leading or trailing spaces. Unless you are certain that you know 
how many leading and trailing spaces the strings have, it is wise to strip them from the strings 
before you combine them. You can always use the + operator to add a single space between 
the two strings if required. 

Leading and trailing spaces are stripped from strings by the functions LTRIMS and RTRIM$ 
respectively. So if, for example, firsts and seconds had been stored earlier, the 
following commands might have been used to produce combinedS: 

firsts - LTRIMS(RTRIMS(firstS)) 
seconds ■= LTRIMS(RTRIMS(seconds)) 
combinedS - firstS+" "+secondS 


4.2 String functions 

The string functions provided are classified into the following classes: 

• converting strings to upper and lower case 

• examining strings: determining their length and whether they contain certain characters 

• generating strings 

• picking out and replacing substrings 

• stripping strings of leading and trailing spaces 

• special strings 



(You can also add your own string functions. See Functions in Chapter 6 'Routines'.) 


Converting strings 

Text strings can include a wide variety of characters, including capitals (upper case) and 
small (lower case) letters. There are two functions to convert letters from upper to lower case 
and vice versa: these are UCASE* and LCASEJ. 

To convert a suing expression to upper case, use: 

UCASES ( string-expression ) 

To convert a string expression to all lower case (ie small letters), use: 

LC AS E$ ( string-expression ) 
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Note that this conversion docs not affect any symbols other than the letters 'a' - 'z' and 'A' - 
Z', and the accented letters. If there is no capital version of an accented character, it will be 
converted to the equivalent unaccented capital character. 
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use 

LTRIMS 

LTRIMS is a function to remove leading spaces from strings. 

Syntax 

LTRIMS (argument) 

where 

argument is a string-expression. 

Description 

LTRIM$ returns argument with any leading spaces removed. 

Use 

RTRIMS 

RTRIMS is a function to remove trailing spaces from strings. 

Syntax 

RTRI M$( argument) 

where 

argument is a string-expression 

Description 

RTRIMS returns argument with any trailing spaces removed. 



LCASE$ & LOWERS 

Use 

These functions to convert characters to lower case. 

Syntax 

LCASE$( argument) 

LOWERS (argument) 

where 

argument is a string-expression 

Description 

LCASES and LOWERS return argument with all the uppercase characters converted 
to the corresponding lower case characters. Other characters are left unaffected. 


UCASES & UPPERS 

Use 

These functions convert characters to upper case. 

Syntax 

UCASE argument) 

UPPERS (argument) 

where 

argument is a string-expression 

Description 

UCASES and UPPERS return the argument with all the lower case characters 
converted to the corresponding upper case characters. Other characters are left ' 
unaffected. 
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Examining strings 

There are two functions that help you to examine strings, by returning the length of a string 
and locating any occurrences of another string within it. 

To find the length of a string, use LEN, which returns the length of its string argument: 

LEN( string-expression) 

For example: 

chars = LEN(title!+name$) 

This is particularly useful when you need to process the string a character at a time, such as in 
the following routine, which displays the string in ti tl eS double-spaced across the screen: 

FOR count = 1 TO LEN(title!) 

PRINT title${count}+" 

NEXT count 
PRINT 

To check whether a string contains another siring, use INSTR. This takes the form: 

IN S TR ( (start . Jstring-expression-1, string-expression-2) 

where start is an integer-expression that specifies where in string-expression-1 to start searching 
for string-expression-2. If start is omitted, the string will be searched from its beginning. 

I NSTR returns a numeric result, which is 0 if string-expression-2 could not be found when 
searching from the given start. If the result is not 0, it is the position in string-expression-1 of 
the start of string-expression-2. 

Conveniently, 0 is also the value assigned to 'false' in control expressions, so it is legitimate 
to write code such as the following: 

If INSTR(sentence$.searchstring!) then process(sentenceS)* 

Generating strings 

To produce a string of the same character repeated, use: 

STRI NG$ ( length, string-expression) 

This produces a string of length characters, consisting of the first character of the given string- 
expression. 






Chapter 4: Working with Strings 


Use 

LEN 

LEN is a function to find the length of a string. (How long is a piece of string?) 

Syntax 

where 

LEN ( argument) 
argument is a string-expression 

Description 

LEN returns the length of argument, that is, the number of characters in the string. 

For a fixed-length string the length returned excludes the first null character and 
all following characters. This is the effective length of the fixed-length string, since 
whenever it is used the first null character and all following characters are. 

INSTR 

Use 

The INSTR function is used to find out if one string is a substring of another. 

Syntax 

where 

IHSJR([start, ]search-string , target-string) 

start is an integer-expression in the range 1 ..4096, and search-string and target¬ 
string are string-expressions. 

Description 

I NSTR searches search-string for target-string , starting the search at the start- th 
character (or the beginning of the string, if start is not present). If the target is 
found, INSTR returns the position in search-string of the first character of the first 
occurrence of target-string. If the target is not found, I NSTR returns 0. 


Use 

STRINGS 

STRINGS is a function to generate a string of repeated characters. 

Syntax 

where 

STRINGS!/eng/Aj, argument) 

length is an integer-expression in the range 0..4096 and argument is a non-null string- 
expression or an integer-expression giving a value in the range 0..255. 

Description 

If arguments a string-expression, STRINGS returns a string consisting of the first 
character of argument repeated length times. 

If argument is an integer-expression , STRINGS returns a string consisting of the 
character whose character code is argument, again repeated length times. 
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For example, the command: 

PRINT STRINGS(20,"*"):"H1!":STRING$(20,"*") 
would produce: 

You don't have to enter the character you want literally: you can give it in the form of its 
internal character code. (For more details of character codes, see Section 4.4 Working with 
character codes' and Appendix I The Character Set'.) 

The character code is used as follows: 

STRINGS ( length, numeric-expression) 

This produces a string of characters, all with the character code corresponding to the given 
numeric expression. For example, STRINGS(20.42) gives a string of 20 asterisks because 
the character code for "*" is 42. 

(Other functions generate strings from numbers. These are described in Section 4.3 'String 
representation of numbers'.) 


Picking out parts of strings 


The simplest way to extract text from within a string is by using substrings. This is a 
particularly powerful technique. 







A substring selector specifies what part of the preceding string to use, as follows: 
string$[ start TO end] 

- extracts a substring starting at Start andfinishing with end. 
string$[ start) 

- extracts a substring consisting of the single character at Start 
string$[start TO) 

- extracts a substring from Start to the end of the String variable 
string$[T0 end) 

- extracts a substring from the beginning of the string variable to end 
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The positions start and end are integer-expressions; they can be positive or negative. If positive, 
they refer to the nth character from the start of the string (first character = 1); if negative, they 
refer to the nth character from the end of the string (last character = -1). Thus, to extract 
characters from the 3rd to last but one character, use: 

string (3 TO -2} 

start and end may be the same, giving a single character substring. If end is before start this 
gives a null substring. 

Using substrings, you can assign characters to any position within an existing string variable. 
In other words, string general-variables qualified with substring brackets can still be used as 
general-variables: 

string-general-variable { range) - string-expression 

For example 

a$ = "frog" 
aS{2) - "1" 

will set a S equal to " f 1 og ". 

Note that assigning in this way never alters the length of the string. If the expression on the 
right hand side of the assignment is longer than the substring specified in the general- 
variable, excess characters are discarded; if the expression is shorter than the substring in the 
general-variable, as many characters as possible are assigned, and the rest are left unchanged: 

a$-"This is a dog" 

PRINT a$ 
a*{ll}-"frog" 

PRINT a$ 

a${ll TO 13}“"frog” 

PRINT a$ 

END 

Will produce: 

This is a fog 
This is a fro 
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There are also three functions that extract text from within a string: LEFTS. MIDS and 
RIGHTS. (They are mainly provided for compatibility with earlier versions of BASIC, as the 
equivalent effects can be achieved more easily using substrings.) 


LEFTS extracts the first length characters from a string (this is equivalent to the substring 
specification {TO length}): 

LEFTS ( string-expression , length ) 


RIGHTS extracts the last length characters from a string (this is equivalent to the substring 
specification {• length TO)): 

RIGHTS! string-expression , length ) 


MIDS extracts length characters starting from star (this is equivalent to the substring 
specification { start T 0 start*length-] )): 

MIDS ( string-expression, start, length ) 


If length is omitted, then MIDS extracts all the characters between start and the end of the 
string: this is equivalent to the subsuing specification { start T0} . 


You can also use MIDS to assign to substrings of string variables. This has been provided 
mainly for compatibility with earlier BASICS. It is used as: 

MIDS( variable.startf . length /) - string-expression 


MID$ - Statement 


Use MIDS assigns a string to a substring. 


Syntax 

where 


MIDS ( string-general-variable. start [. length ]) - string-expression 

start and length are integer-expressions, each of which must give a value greater 

than or equal to zero. Neither may be greater than 4096. 


Description MIDS assigns the result of the string-expression to the substring of the string-general- 
variable which islength characters long starting at its s/art-th character. If length is 
omitted then 1 is assumed. If length and start have values which take the substring 
beyond the end of the string-general-variable, no error is raised, and MIDS assigns to 
much as possible, which may be nothing at all. If the result of the string-expression is 
shorter than the sub-string then the excess right hand end of the sub-string is 
unaffected. If the result of the string-expression is longer than the sub-string then the 
excess is discarded. 




i < 
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RIGHT$ 

Use 

The RIGHTS function truncates a string by selecting only its rightmost characters. 

Syntax 

RIGHTS (argument. length) 

where 

argument is a string-expression and length is an integer-expression returning a 
value in the range 0..4096. 

Description 

RIGHTS returns the last length characters of argument. If length is longer than 
argument, the whole of argument is returned. 


LEFTS 

Use 

LEFTS is a function to truncate a string by selecting only its leftmost characters. 

Syntax 

L E F T S ( argument. length) 

where 

argument is a string-expression and length is an integer-expression returning a 
value in the range 0..4096. 

Description 

LEFTS returns the first length characters of argument. If length is longer than 
argument, the whole of argument is returned. 


MID$- Function 

Use 

MI D$ is a function to select a substring from a given string. 

Syntax 

M IDS (argument, start l, length]) 

where 

argument is a string-expression 

start and length are integer-expressions, start must give a value greater than 
zero; length must give a value greater than or equal to zero. Neither may be 
greater than 4096. 

Description 

MI DS returns the substring of argument which \slength characters long starting at the 
s/art-th character of argument. If length is omitted then 1 is assumed. If length and start 
have values which take the substring beyond the end of string-expression., no error 
is raised, and MIDS returns as much as possible, which may be nothing at all. 
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Special string functions 


A function OATES produces a string giving the date in the conventional form (eg. 21/03/86). 
Without arguments, DATES gives the current date; with an argument, DATES (integer- 
expression) gives the specified number of days since 31st December 1899 as a date string. The 
format for the date is the same as for the numeric DATE function, described in the last chapter. 

Similarly TIMES produces a string of eleven characters giving the time to the nearest 
hundredth of a second: 13:14:20.71 


DATES 

Use DATES is a function which converts a date as a number of days since 31st 

December 1899 to a date in the form of a string. It is the inverse function of DATE. 

Syntax DATE$/( argument)) 

where argument is an integer-expression, giving a positive, non-zero, value. 

Description DATES returns a string giving in conventional form the date of the day which fell 
argument days after 31 December 1899. 

The conventional form depends on the country code of the computer's operating 
system, but for the United Kingdom it consists of the day, the month and the year, 
in that order, each represented by one or two digits, and separated from each 
other by slashes, for example 13/ 3/56. Conventional form for dates can be 
changed using the OPTION DATE statement. 

If argument is omitted, the current date is returned. 


TIME$ 


Use 

Syntax 

Note 


TIME is a function which returns the number of hundredths of a second which 
have elapsed since midnight, to the nearest hundredth, in the form of a string. 

TIMES 

TIMES returns an eleven character string of the form " 1:59:59.01", giving 
hours, minutes, seconds and hundredths of a second. The hours field will contain 
a space in place of any leading zero, the other fields will have leading zeros if 
their value is less than ten. 

This value is derived from the system clock. Note that the unit of time used by the 
the system clock limits the precision to which time may be measured, and, in 
particular, that this unit may be greater than a hundredth of a second. 
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4.3 String representation of numbers 

Numeric values cannot be used as strings, nor can strings be used as numeric values, but 
functions are provided to convert numeric values to strings and vice versa. 

Free format representations 

The three functions, STRS,HEXS and BINS, convert numbers into strings of digits. 

STRS ( integer-expression) converts a numeric value to the equivalent decimal string. This 
produces exactly the same string as would output by the command PRINT integer-expression. 

H E X S ( integer-expression[, min-length ]) converts an integer to the equivalent hexadecimal 
string. 

BIN S ( integer-expression [, min-length ]) converts an integer to the equivalent binary string. 

All three will always give as many characters as required to represent the number. However, 
an optional extra field-size parameter can be specified for HEXS and BINS which gives the 
minimum number of digits in the string. This can be any number between 0 and 32. If the 
string is shorter than this, then it is padded out with leading zeros. The string is not truncated 
if it is longer. 



HEX$ 

Use 

HEXS is a function which converts an integer value to a string of hexadecimal 
digits. 

Syntax 

H EX $ ( argument [, min-digits ]) 

where 

argument and min-digits are integer-expressions , min-d'igits must give a value in 
the range 0..32. 

Description 

HEXS evaluates argument, and returns its value represented as a string of 
hexadecimal digits, in 32 bit 2's complement form. No leading &H characters are 
added. 


* 

Leading zeroes are stripped if min-digits is not present. If min-digits is present, : 

enough leading zeroes are added to make the string at least min-digits digits long. 

(If the string is already min-digits long, or longer, it is not truncated.) 
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STR$ 

Use 

STR$ is a function to convert a numeric value to string form. 

Syntax 

STR S(. argument) 

where 

argument is a numeric-expression. 

Description 

STR* returns the value of numeric-expression as a decimal string. The format of the 
string is as if it had been printed unformatted with a PRINT statement, assuming 
the largest possible print zone. 


BIN$ 

Use 

BIN* is a function which converts an integer value to a string of binary digits. 

Syntax 

BI N* ( argument [. min-digits]) 

where 

argument and min-digits are integer-expressions] min-digits must give a value in 
the range 0..32. 

Description 

BINS evaluates argument, and returns its value represented as a string of binary 
digits, in 32 bit 2’s complement form. (No leading AX characters are added.) 


Leading zeroes are stripped if min-digits is not present. If min-digits is present, 
enough leading zeroes are added to make the string at least min-digits digits long. 

(If the string is already min-digits long, or longer, it is not truncated.) 



DEC$ 

Use 

DEC* is a function which converts a numeric value to a formatted decimal string. 

Syntax 

DEC i(argument , template) 

where 

argument is a numeric-expression, and template is a string-expression. 

Description 

DEC* returns the value of argument as a string in decimal representation, formatted 
according to template. 


template is treated exactly as if it followed the word US ING in a PRINT statement. 

The template may only contain characters drawn from the set: 


+ -'**#. . \ A 
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Formatted representations 

Another function, DEC$, converts a numeric expression to a formatted decimal string. 

DECS ( numeric-expression,format-template ) 

The format-template is a string-expression that dictates how the number will be formatted, using 
a subset of the facilities of a PRINT USING template (see Chapter 11). It does so using the 
characters 4 - $ * * , . and *, as follows: 

Each * in the template specifies a digit position. If there is no ., only the integer part of the 
number will be output, with no decimal point If there is a ., a decimal point will be output at 
this position. The number is rounded to the number of places output. 

A , anywhere to the left of the . (if present) specifies that digits to the left of the decimal 
point will be grouped into threes, separated by commas. Thus, to format the string to 4 digits 
and no decimals, the template would be: 

"####" 



To produce 9 digits, grouped into threes, with 2 decimal places, the template would be: 

Note that it is good style to put commas in the template after every third #; this keeps the 
template to the same length as the number which will be printed. 

(You can use other characters as the decimal point and thousands separator characters: see 
■National variants', in Chapter 11.) 



If the numeric expression being converted is too small to fill the template, leading places will 
be filled with spaces. If it is too large, the template is extended as necessary. 

Positive numbers will normally be printed without a sign, negative numbers with a leading 
negative sign (which occupies one of the digit positions specified by a * or the position 
specified by a leading -). 

To specify that the minus sign be output at the end of the string for negative numbers, place a 
at the end of the template. To specify that a V sign be output for positive numbers, place it 
either at the start or end of the template; plus and minus signs will then both be output at this 
position. 

To specify that instead of leading spaces, leading asterisks should be output, place * * at the 
start of the template (but after any leading sign). This also specifics two further digit 


_ -ry 
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positions. To specify that the number should start with a $ sign, put $ $ at the start of the 
template (but after any leading sign). This specifies an extra digit position. To specify both 
leading asterisks and a leading ), place * * $ at the start of the template (but after any leading 
sign) - this also specifies an extra 2 digit positions. (You can also specify other characters for 
currency symbols: see 'National variants', in Chapter 11.) 

Thus, to produce strings with leading asterisks instead of spaces, 6 digits and a trailing minus 
sign, the template would be: 

To specify 9 digits in groups of three, 3 decimal places, leading asterisks, $ and either a ♦ or 
a - sign: 

"+**%.mmn.mr 

Finally, you can specify that the number be output using an exponent, by adding A * * A to 
the end of the template before any trailing sign; or you can use A * A * which has a similar 
effect, but produces an exponent that is a multiple of 3 (as used in engineering). 

If you wish to force a three-digit exponent the corresponding forms have an extra carat: 

AAAAA gpjj A A A A ★ 


4.4 Working with character codes 

Each character in a string is not held literally as the character but as an 8-bit code. This code 
is a combination of Os and Is but is most usefully thought of as either a decimal number in the 
range 0...255 or a hexadecimal number in the range &00...&FF. 

The character associated with each code is defined by the Character Set BASIC 2 Plus uses 
the GEM Character Set (detailed in Appendix I). 

Entering characters by using their character code 

You can enter characters from their character codes by using the function CHRJ. This is 
particularly useful where you can't type the character directly. 

The function CHR$ returns the character corresponding to a given code: 

CHR$( code) 

Thus the BE L character, which has GEM code 7, cannot normally be typed directly. But you 
can output a BE L with the statement: 

PRINT CHR$(7) 
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ASC 


Use AS C is a function which converts characters to their numeric character code 
representation. 

Syntax ASC (.argument) 


where argument is a string-expression giving a non-null string 


Description ASC returns the character code for the first character of argument. 



CHR$ 


Use CHR$ is a function which converts a character code to a single character string. 
Syntax CHR %(. argument) 


where argument is an integer-expression in the range 0..255. 

Description CHR$ returns a string containing one character: the GEM character corresponding 
to argument. 


Working with a character's character code 


You can work with the character code, rather than the character, by using the function ASC. 

ASC returns the code of the first character in its string argument. For example: 

PRINT ASCC'ABCD") 

would print 64, because that is the character code for "A". If the argument is a null string, ASC 
case because upper-case characters have lower internal values. 
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4.5 Comparing strings 


You can compare strings with the aid of the relational operators: 


<> 


> 


>-or=> 


<-or-< 


< 


less than 

less than or equal to 
equal to 

greater than or equal to 
greater than 
not equal to 


When comparing strings, BASIC 2 Plus looks at the internal values of corresponding 
characters, up to the first character where these are not identical. The string containing the 
character with the smaller internal value is ’less than' the other string. 

This means a suing in upper-case is less than the same suing in lower-case because upper¬ 
case characters have lower internal values. 

If all the corresponding characters match, then the strings are equal provided they are the 
same length. Otherwise the longer string is greater. 

Leading and Uniting spaces are significant in these comparisons. Each space is simply a 
character with internal value 32. 









Chapter 5 


Flow of Control 



This chapter describes the BASIC 2 Plus facilities that let you control the order in which 
statements are obeyed and the number of times they are obeyed. There arc several types of 
action: 

selection, ie. choosing between alternative groups of statements. BASIC 2 Plus uses IF 
statements and SELECT CASE statements to make decisions like this. There is also the ON 
statement, which is largely superseded by SELECT CASE, but has been provided so that 
BASIC 2 Plus will be compatible with older BASICS. 

repetition, ie. repeating groups of statements in a loop. BASIC 2 Plus has two kinds of loop: 
the FOR loop, which is used when you know how many times you want to repeat the 
statements, and the DO loop, which is used when you want to go on repeating statements 
while some condition holds, or until some particular condition is met The DO loop is a more 
powerful version of the old REPEAT and WHILE loops, though these are retained for 
compatibility with other BASICS. 



sequence changing, ie. directly altering the order in which statements are obeyed. This is 
done with GOTO. This used to be a very important statement in older versions of BASIC, but 
more powerful features have made it less necessary, and nowadays well-written BASIC 
programs only use it in unusual circumstances. 


o 

o 



• stopping before the end of the program is reached. The statements for this are END and STOP. 
There is also the CONT statement, which can be entered into the dialogue window to allow a 
STOPpcd program to CONTinue. 


5.1 IF statements 


IF is used to start a variety of decision-making structures, using the keywords IF, END IF, 
ELSE IF, THEN, and ELSE. IF and ELSE IF evaluate a condition to ’true’ or 'false', to decide 
which of the subsequent statements are executed. 


o 

3 
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Simple IFs 


The simplest form is: 

IF condition THEN true-statements 

where condition is a truth-value, and true-statements is a sequence of one or more statements 
separated with colons. 

If condition is true, all the true-statements are obeyed, otherwise execution continues on the 
next line. For example, with: 

IF count < 10 THEN PRINT "Less than 10.":INPUT "New value"jeount 

the PRINT and INPUT statements will only be executed if count < 10 ie. if the variable 
count has a value less than 10. 

Note that IF condition THEN statement is treated as a single statement; there is no need for a 
colon after THEN. 

This simple IF can be made to obey a different group of statements if condition is not true by 
including the keyword ELSE: 

IF condition THEN true-statements ELSE false-statements 

true-statements will only be obeyed if condition is true, talse-statements only if it is not true. In 
either case, execution will continue on the following line. 


Multi-part IFs 


The simple IF described above just allows you to take either of two actions depending on the 
value of a given condition. A multi-part IF allows you to build up a whole range of 
alternative statements. 

Multi-part IFs use two additional keywords: ELSEIF introduces further conditions to be 
tested if the original condition turns out to be false; END IF marks the end of the IF 
statement. 

You can have as many ELSEIFs as you want, and they are only evaluated when all the 
previous conditions are false. (Note the spelling of ELS El F, by the way. Some languages 
spell it without the second 'E'.) 

The ELSE part, if included, must come after any ELSEIF and the whole statement must be 
finished by END IF. 
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IF (single line version) 


Use 


Syntax 

or 

where 


This version of the IF statement is used to choose between two courses of 
action. It is retained only for compatibility with earlier versions of BASIC. 

IF testvalue(colons 7THEN [instructions]((colons JELSE elseinstructions] 

IF testvalue[colons 7GOTO location[[colons /ELSE elseinstructions] 

testvalue is a truth-value 

instructions and elseinstructions are either (a) a line number, or (b) a sequence of 
BASIC statements, separated by colons 

colons is a sequence of one or more colons, but not new lines. 

GOTO can be spelt as two words: GO TO. 

Description testvalue is evaluated. If it returns 'true' (ie. a non-zero value) then 

a) if there is a GOTO, control passes to the location specified by the GOTO or 

b) if there is a THEN the instructions are processed: if instnjctions consists of a line 
number, control passes to that line; if instructions is a sequence of BASIC 
statements, these statements are executed before control passes to the line 
following the IF statement. 

If testvalue returns 'false' (ie. zero) then elseinstructions are processed unless there is 
no ELSE part, in which case control passes to the next statement without error. 

See also: IF... END IF 


Layout of IF statements 

The above IF statements were presented on single lines. This is a perfectly valid way of 
writing IF statements. 

However, writing the complete set of conditions on a single line is not an ideal way of laying 
out an IF statement. The statements can turn out very long and complicated - and therefore 
difficult to read and interpret. Also the length of a single line is limited to 2SS characters. 
Complex conditional statements arc more easily understood if they are presented over a 
number of different program lines as follows: 
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IF count>0 THEN 

PRINT "Count is positive" 

ELSEIF count < 0 THEN 

PRINT "Count is negative" 

ELSE 

PRINT "Count is zero" 

END IF 

Note the layout of these lines, with the statements on a different line from the IF, E LS EIF or 
ELSE clause. The indenting we have shown is not obligatory but it makes the block 
considerably more readable. 

BASIC works down this block from the top, determining whether each condition is true or 
false and skipping the blocks of statements until it finds one that is true. It then executes the 
block of statements following this true condition (or the one following the E LS E if none is 
true), before skipping to the statement beyond the END IF. 

Nesting IF statements 

IF statements can be nested ie. can themselves be used as statements in IF statements. This 
allows you to express any pattern of branching through a sequence of conditions and sub¬ 
conditions. For example: 

count-100 
IF count > 0 THEN 
PRINT "Count is Positive" 

IF count > 50 THEN 
PRINT "Count is greater than 50" 

ELSE 

PRINT "Count has a value less than or equal to 50" 

END IF 

ELSEIF count < 0 THEN 
PRINT "Count is negative" 

IF count <-50 THEN 

PRINT "Count has a value less than -50" 

ELSE 

PRINT "Count has a value greater than or equal to -50" 

END IF 
ELSE 

PRINT "Count Is Zero" 

END IF 
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IF...END IF 

Use I F...END IF is used to choose between various courses of action depending on 
the values of various expressions. 

Syntax IF testvaluel[: [THEN (: ]statemenlsl [: ] 

[ELSEIF te$tvalue2[: /THEN/: ] statements2 [: ]] 

/ELSEIF testvalue3[: /THEN [: ]statements[: ]] 

[ELSE [: ]elsestatements[: ]] 

END IF 

where the testvalues are truth-values, and statementsl, statements2,... and elsestatements are 

sequences of BASIC 2 Plus statements, separated with colons or new lines in the 
usual way. 

Note that this syntax description, like others in this manual, uses a colon to 
indicate either a colon or a new line. New lines in the syntax description itself are 
only for clarity, and need not appear as new lines in the program. 

The first line of an I F...END IF must not have the same form as a single-line IF. 
It is recommended that a new line be used before or after the first THEN. 

Description testvaluel is evaluated, and if it returns 'true' (ie. a non-zero value) statementsl are 
executed, and control passes to the line following END IF. If, on the other hand, 
testvaluel is false' (ie. zero) then testvalue2, testvalue3, etc. are evaluated in turn until 
one of them returns 'true'. As soon as this happens, no further testvalues are 
evaluated, but the corresponding statements are executed and control passes to 
the line following the END IF. 

If none of the testvalues is 'true', the sequence elsestatements is exectuted, if it is 
present. If there is no E LS E line, execution continues with the statement after the 
END IF. No error is raised in this case. 

See also: IF (single line version), SELECT CASE 
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The best way of laying these out is in the multi-line format shown above and structured by 
using different degrees of indentation, as follows: 

IF condition-1 THEN 
IF subcondition-1 THEN 
true-statements 

ELSEIF sub-condition-2 THEN 
true-statements 
ELSE 

false-statements 

END IF 

ELSEIF condition-2 THEN 
IF subcondition-1 THEN 
true-statements 

END IF 


• • • 

END IF 

BASIC itself doesn't interpret the indentation. It simply matches each END IF to the nearest 
previous unmatched IF. To get the program to do what you want, you need to ensure that the 
IFs and END I Fs are properly matched. This is helped by indenting as recommended above. 



5.2 SELECT CASE statements 



SELECT CAS E statements perform a very similar role to IF statements. Both of them pick out 
actions to be carried out when particular conditions are met. In fact, it is always possible to 
constructan IF statement that carries out the same task as a SELECT CASE statement. 

The advantage of SE LECT CAS E is that it evaluates a single expression and then carries out 
different statements depending on the value of the result Where you want to carry out 
different statements depending on the value of one particular expression, SELECT CASE 
gives a method which is neater than using several I Fs. (This is particularly true if the 
expression is a complicated function; the function can be evaluated just once if you use a 
CASE statement, but it will have to be evaluated several times or stored in a temporary 
variable if you are using several I Fs.) 

SELECT CASE also provides better way of handling the type of branching carried out by the 
ON statement used in other BASICS. Whereas the ON statement requires the expression to 
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SELECT CASE 

Use 

SELECT CASE is used to choose one course of action from several, the choice 
being determined by the value of a given expression. 

Syntax 

SELECT CASE selector-expression[:] 

(CASE testvaluesl [. testvaluesla ](. testvalueslb (...: stalementsl: ] 

(CASE testvalues2[, testvalues2a][ . testvalues2b )... : statements2: ] 

where 

(CASE ELSE : elsestatements : ] 

END SELECT 

statements1, stalements2, statements3, .... and elsestatements are sequences of BASIC 
statements separated by colons or new lines in the usual way 

testvalues may be either of the form 
expression (TO end-expression J 
or IS relation limit-expression 

where all the expressions must be of the same type as selector-expression. 


Note that in the above syntax, new lines are used only for clarity. Where syntax 
demands a statement separator (a new line or a colon), a colon has been used. 

Description 

Firstly, selector-expression is evaluated. Then each testvalue in turn is evaluated, 
sequentially from left to right along each CASE line until one is found which is 
satisfied by selector-expression. Thereupon no further values are evaluated, the 


statements corresponding to the satisfied testvalue are executed, and control 
passes to the statement after the END SELECT statement. If no testvalue is 
satisfied, the elsestatements are executed if there is a CASE ELSE line; if not, an 
error results. 


A selector-expression satisfies a testvalue in one of three cases: 

if the testvalue consists of just an expression, the selector-expression must be 
equal to it. 

if the testvalue consists of two expressions separated by TO, the selector- 
expression must lie between the expressions, or be equal to one of them. 

if the testvalue contains IS, then replacing IS with the value of selector-expression 
must evaluate to 'true', ie non-zero. 

See also: 

ON...GOTO 
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return one of the values 1,2,3 etc., SELECT CASE will handle any value of the expression 
- numeric or string - either given explicitly, or falling within a given range of values. (You 
can still use ON if you wish; it has been retained to make BASIC 2 Plus compatible with other 
BASICS.) 

The structure of a SELECT CASE statement is as follows: 

SELECT CASE selector-expression 
CASE values 
statements 

/CASE ELSE 

else-statements] 

END SELECT 

Note similarity to a multi-part IF; also that CASE ELSE, if included, must come after all the 
other CASE statements. 

selector-expression is the expression whose value is used to determine which statements 
should be executed. It can be either a numeric-expression or a string-expression. 

values represents a list of the values of the expression for which the following statements 
should be executed; the values should be separated by commas. Each value is itself an 
expression of the appropriate type. 

When BASIC interprets the SELECT CASE statement, it first evaluates the expression and 
then searches for the value it finds among those listed in the various CASE statements. It then 
executes the block of statements that follow the CASE statement, and then it jumps to the 
statement immediately following END SELECT. If it doesn't find the value in any of the CASE 
statements, it executes the statements following CASE ELSE (if this has been included) or 
raises an error (if it hasn’t). CASE E LS E can perform a very useful role in handling unforeseen 
values of selector-expression. 

Ranges of Values in SELECT CASE Statements 

Where appropriate, the list of values can also include a range of values, written as expression 
TO expression. The lesser value has to come first. (In the case of negative values, the lesser 
value is the more negative number.) For example, values from 2 to 10 (inclusive) would be 
specified as 2 TO 10. 
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The other option is to express the values you want to pick out in a relational expression. This 
allows you to specify, for example, values of the expression less than 10. This is written in 
the list of values as IS relational-operator expression. Values less than 10 would therefore be 
written as IS < 10; values greater than 1 would be written as IS > 1. For example: 

SELECT CASE 1 ength_of_service 
CASE IS < 12 : discount - 0 
CASE 12 TO 24 : discount - 3 

CASE 24 TO 35 : discount - 7 

CASE 36 TO 47 : discount - 10 

CASE IS >= 48 : discount = 15 

CASE ELSE : PRINT "Invalid Input." 

END SELECT 


8^3 


Nesting SELECT CASE statements 


SELECT CASE statements can be nested, just like multi-part I Fs. This gives you a very easy 
way of coding a pattern of branching that depends on the value of more than one variable. For 
example... 

With suitable indenting, the resulting structure might be something like this: 



SELECT CASE variable-1 
CASE values-1 

SELECT CASE variable-2 
CASE values-2 

END SELECT 
CASE values-1 

SELECT CASE variable-3 
CASE values-3 

END SELECT 

/CASE ELSE 
statements J 
END SELECT 



However, if you use more than two levels of nesting, the resulting code will become very 
difficult to read. You will probably be much better off recasting some of the CASE statements 
into separate routines (see Chapter 6) 
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ON. .GOTO 

Use ON is a relic from older BASICS, included to make BASIC 2 plus compatible. It has 
a very similar use to S ELECT CASE, namely, that depending on the value of an 
integer expression control can be passed to several different points in the 
program. 

Syntax ON condition GOTO [locationl][, [ location2]](, (locations ]}... 
where condition is an integer-expression 

locationl, location^ locations, etc are locations. 

GOTO may be spelt as two words thus: GO TO 

Description The integer expression condition is evaluated, and if it evaluates to 1,2,3, etc, 
control is passed to locationl,location2, locations, etc, if they are present. If they are 
not present, control passes to the next statement, without error. 

See also: SELECT CASE 


5.3 FOR...NEXT loop 

Many of the tasks that you program will involve repetition of similar or identical steps. This 
section and the next describe how to code such repetition easily and efficiently. 

Statements are repeated by including them in loops'. 

Loops can be constructed using GOTO and IF but BASIC 2 Plus's pre-defined looping 
structures are far superior. These provide two main types of loop - ones that are repeated a 
fixed number of times, and 'open-ended' loops, which are repeated until some predefined 
condition is met. 

Statements that are to be repeated a fixed number of times are handled by a FOR loop; 
statements that are to be repeated until a particular condition is true or while a condition is 
true are handled by a DO loop. (Thereare also REPEAT loops and WHILE loops, which are 
retained principally for compatibility with other BASICS. The DO loop offers greater 
flexibility than either of these.) 

This section describes the FOR loop; DO loops are described in the next one. 
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The FOR loop is used when the number of times the loop should be executed is known at the 
start of the loop, for example, when processing each element of an array in turn. The FOR 
loop starts with a FOR statement and ends with a NEXT statement: 

FOR loopcounter - start TO end /STEP stepsize] 
loopbody 

NEXT lloopcounter / 

{loopcounter is a simple-numeric-variable, start, end, and stepsize are numeric-expressions, and 
loopbody is a sequence of statements separated with colons or new lines in the usual way.) 

The loopcounter on the NEXT statement is checked against the loopcounter on the FOR 
statement; if they are not the same, an error is generated. It is not necessary to follow NEXT 
with a repetition of loopcounter, but nevertheless it is good programming practice. 

Ignoring the optional STEP keyword for the moment, the loop is executed as follows: 

1 loopcounter is set to start , and end is evaluated and stored 

2 If loopcounter is greater than end, the FOR loop finishes immediately, and the program 
continues from the statement after the NEXT 

3 Assuming start is less than or equal to end, the statements in the loopbody are obeyed as 
normal 

4 When NEXT is reached, loopcounter is incremented by 1, then execution continues from 
step (2) 

The optional STEP keyword is used to specify an increment (other than the default of+1) for 
use in step (4). stepsize may be positive or negative; if it's negative, the loop terminates when 
loopcounter is less than end, rather than greater than end. 

The steps you use don't have to be integer, however, you should use fractional steps with 
care. Because of rounding at each stage, the number of loops actually executed needn't be the 
number you would expect 

To improve legibility, it is usual to indent the loop body with leading spaces, as shown. The 
editor's auto-indent option makes this very easy to do. 

The control variable can be used by statements within the loop body. It can even changed by 
them, but this is not advisable as it can lead to elusive bugs. When the loop finishes, the value 
of the control variable is preserved, that is, it is approximately start plus Step times the number 
of times the loop is executed. The FOR statement evaluates start and end when is executed; if 
the loop body changes the value of these it will have no effect on looping. 


_ 
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FOR 

Use The FOR statement is used to repeat a group of statements where the number of 
repetitions is known or can be calculated at the time the loop is entered. 

Syntax FOR loopcounler - start TO end /STEP stepsize]: loopbody : NEXT... 
where loopcounter is a simple-variable, not a VAR or ref formal parameter. 
start, end, and stepsize are numeric-expressions 

loopbody is a sequence of BASIC 2 Plus statements, separated in the usual way 
with colons or new lines. 

Description The expressions stepsize, start and end are evaluated, and loopcounter is set equal to 
start. 

The statements in loopbody are then executed repeatedly, in sequence. 

At the end of each pass of loopbody, loopcounter is incremented by stepsize. 

This process continues until the increment makes loopcounter strictly greater than 
end. When this happens, control is passed to the statement after the matching 
NEXT. 

If end is equal to start, loopbody is executed once. If end is less than start, loopbody is 
not executed at all (unless stepsize is negative - see below). 

stepsize may be omitted, in which case it is taken to be 1. It may be negative, in 
which case loopbody is executed until loopcounter is strictly less than end. In this 
case, loopbody is not executed at all if end is greater than start. 

It is an error for stepvalue to evaluate to 0. 

start and end are evaluated once only, before the first pass of the loop. They may 
be altered by statements in loopbody without affecting the terminating conditions. 

loopcounter retains its final value after the loop is terminated, and may be used by 
the rest of the program. 

See also: NEXT, EXIT FOR 


)6 


8 








Chapter 5: Flow of Control 


NEXT 

Use Terminates the sequence of statements which make up the body of a FOR loop. 

Syntax NEXT (loopcounterl][, [ loopcounter2 } ] [. [ loopcountert]}... 

Description NEXT terminates the sequence of statements which make up the body of a FOR 
loop. 

If there are no commas after NEXT, it terminates the loopbody of the nearest 
preceding unmatched FOR statement. It loopcounterl is included, it is checked 
against the loopcounter of the FOR statement, and if they do not match, an error is 
raised. ' 

If there are any commas after NEXT, it terminates more than one FOR statement: 
the number of FOR statements terminated is one more than the number of 
commas. If loopcounters are included, they are checked against the loopcounters 
of the corresponding FOR statements: the loopcounter before the n-th comma 
must match the loopcounter of the n-th most recent FOR loop, and the loopcounter 
after the final comma must match the (m-l)-th FOR loop. 

See also: FOR 


Nesting FOR loops 

The loop body can include most statements, including other FOR loops ie. FOR loops can be 
nested, each with its own NEXT statement marking the end of the loop. Nested FOR loops 
should use different control variables. 

The best way of laying out nested loops is to use different degrees of indentation, as follows: 

FOR i=l TO 10 
FOR j=l TO 4 
loop-body 
NEXT j 
NEXT i 

BASIC itself doesn't interpret the indentation: it simply matches each NEXT statement to the 
nearest previous unmatched FOR. 
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5.4 DO...LOOP 

Loops repeated an unspecified number of times 

If the number of times a loop should be executed is not known at the start, a different type of 
loop is used - a DO loop. In a DO loop, looping is controlled by a test made before or after 
(or before and after) each repetition. The programmer has to make sure that something alters 
during the course of the loop (it will probably be the value of a variable) so that sooner or 
later the test controlling the loop will make the loop finish. 

If the test is only carried out at the end of the loop, then the statements within the loop will be 
carried out at least once: if there is a test at the start of the loop, then the statements can be 
skipped altogether. 

All of these options are expressed by the DO loop. The WHILE...WEND and REPEAT 
... UNTIL loops that you may be familiar with from other BASICS may also be used. They 
are not as powerful as the DO loop, but are included for compatibility with other BASICS. 

The DO loop starts with a DO statement and ends with a LOOP statement Either the DO 
statement or the LOOP statement (or both, or neither) can contain the details of a test that 
should be carried out in order to determine whether the loop should be repeated. This 
condition is introduced by the keyword WHILE or UNTIL, depending on whether the loop 
statements are to be repeated while the condition is true (ie. passed over when the condition is 
false) or until the condition is true (ie. passed over when the condition is true). 

• The first variant we'll look at is the one which tests a condition at the start of the loop and 
repeats the loop while this is true. The form of this statement is: 

DO WHILE condition 
loop-body ' 

LOOP 

condition is a Boolean expression as described in Chapter 3. loop-body is the block of 
statements to be repeated. 

When the DO WHI LE statement is reached, the loop is executed as follows: 

1 condition is evaluated. If it's false, the loop ends and execution continues with the statement 
after LOOP. Otherwise: 

2 The statements in loop-body are obeyed as normal 

3 When LOOP is reached, processing continues from step 1 
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Use 


Syntax 

where 


Description 


The DO statement is used for repeating a sequence of statements when the 
repetition is governed by some condition which may be tested before or after the 
execution of the loop. 

DO f terminating-condition 1]: loopbody: LOO P f terminating-condition 2] 

terminating-conditions are either 
WHILE truth-value 

or UNTIL truth-value ' 

loopbody is a sequence of BASIC 2 Plus statements, separated in the usual way 
with colons or new lines. 

If there is a terminating-conditionl, it is evaluated. If this condition permits execution 
of loopbody (see below) or if there is no condition attached to the DO, then loopbody 
is executed. 

When LOOP is reached, if there is a terminating-condition2 it is evaluated. If it permits 
execution of loopbody, or if there is no condition attached to the LOOP, then control 
passes back to the DO statement, which is once again executed. 


When a terminating-condition is < 
executed, control is immediately passed to the statement following the LOOP. 

WHILE condition permits execution of loopbody if condition evaluates to true*, ie. not 
zero. 

UNTIL condition permits execution of loopbody if condition evaluates to false’, ie. zero. 
See also: EXIT DO 


BASIC 2 Plus: Language Reference 














This version of the DO loop can also be written as a WHILE.. .WEND loop with exactly the 
same effect: 

WHILE condition 
loop-body 
WEND 

It is important to appreciate that the statements in loop-body won't be executed at all if the 
condition is false when the loop is entered. 

• The second variant we'll look at is the one which tests a condition at the end of the loop and 
repeats the loop until this condition is true. The form of this statement is: 

DO 

loop-body 

LOOP UNTIL condition 

Again, condition is a Boolean expression and loop-body represents statements to be repeated. 

When the DO statement is reached, the loop is executed as follows: 

1 Statements in loop-body are obeyed as normal 

2 When LOOP UNTIL is reached, condition is evaluated. If it's true, the loop ends and 
execution continues with the statement after LOOP. Otherwise (ie. if condition is false) 
processing continues from step 1 

Notice that the statements in the loop will always be executed at least once. 

This version of the DO loop can also be written as a REPEAT... UNTIL loopt: 

REPEAT 
loop-body 
UNTIL condition 

• The other variations - DO UNTIL.. .LOOP and DO... LOOP WHILE - can be analysed 
similarly: 

DO 

loop-body 

LOOP WHILE condition 

will execute loop-body at least once, and will terminate at the end of the loop if condition is 
false. It can be written as a REPEAT statement thus: 

REPEAT 

loop-body 

UNTIL NOT condition 
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WHILE 

Use 

The WHI IE statement is used for repeating a sequence of statements when the 
repetition is governed by some condition which may be tested before or after the 
execution of the loop. 

Syntax 

where 

Description 

WHILE condition : loopbody : WEND 

condition is a truth-value 

loopbody is a sequence of BASIC 2 Plus statements, separated in the usual way 
with colons or new lines. 

condition is evaluated, and if it evaluates to true’, (i.e. not zero) the statements in 
loopbody are executed. When WEND is reached, the whole statement is repeated; 
ie. condition evaluated and if necessary loopbody is executed. 

This sequence continues repeatedly until condition evaluates to false' (ie. zero). 


When this happens, control passes immediately to the statement following the 

WEND. 


REPEAT 

Use 

The REPEAT statement is used for repeating a sequence of statements when the 
repetition is governed by some condition which may be tested before or after the 
execution of the loop. 

Syntax 

REPEAT : loopbody: UNTIL condition 

where 

condition is a truth-value 


loopbody is a sequence of BASIC 2 Plus statements, separated in the usual way 
with colons or new lines. 

Description 

The statements in loopbody are executed, then the Boolean expression condition is 
evaluated. If it evaluates to 'false', (ie. zero) the REPEAT statement is repeated; in 
other words, loopbody is executed repeatedly, and condition is evaluated after each 
pass of the loop until it evaluates to fate' (ie. non zero). 


When condition is evaluated and returns true', control passes immediately to the 
statement following the UNTIL. 
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The last variation on this theme is 

DO UNTIL condition 
loopJxxty 
LOOP 

which will execute the loop repeatedly until condition is true. It will not execute the loop at 
all if condition is true at the start of the loop. The alternative form is 

WHILE NOT condition 
loofybody 

WENO 


Nesting DO loops 

The loop-body can include most statements, including other 00 loops (or equivalents); in other 
words, 00 loops can be nested. 

Each 00 will need its own LOOP statement marking the end of the loop. LOOP statements are 
simply-matched to the nearest previous unmatched 00. 

If a 00 loop is nested inside a FOR loop, then both the DO and the LOOP statements must be 
inside the FOR.. .NEXT loop. Similarly, if the FOR.. .NEXT loop is the inner loop, both the 
FOR and the corresponding NEXT must lie between the DO and the LOOP statements. 


5.5 Exiting from a loop 

The FOR loop is automatically terminated when the loop counter is found to be greater than 
the end value (or less than the end value, in the case of negative steps). The DO loop is 
automatically terminated when testing shows that the WHILE condition is false or the UNTIL 
condition is true. 

But loops can also be left part way through. The statement to use to leave a FOR loop is 
EXIT FOR; the one to leave a DO loop is EXIT 00. The result of the EXIT statement is what 
you might expect from its name - it finishes the current loop at that point. 

This means that control is transferred to the statement that immediately follows the loop, and 
the next statement to be executed will be the one following the loop's NEXT or LOOP: 
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EXIT DO, EXIT FOR 

Use EXIT DO and EXIT FOR are used to get out of a loop from the middle without 
waiting for the loop to complete. EXIT DO and EXIT FOR are used to leave DO 
and FOR loops respectively. 


Syntax EXIT DO 
or EXIT FOR 

Description When an EXIT statement is executed, control passes immediately to the end of 
the current loop - the current DO loop for an EXIT DO, dr the current FOR loop for 
an EXIT FOR. 


FOR I - ... 

... EXIT FOR 

NEXT I 
(next statement) 

Where the loop is nested within other loops, the current loop is exited but the outer loops 
continue. For example: 

FOR I = ... 

FOR J = ... 

...EXIT FOR 

NEXT J 
NEXT I 
(next statement) 

When the EX IT FOR in the above example is executed, the J loop is executed but the current 
I loop continues. 

There is no corresponding EXIT statement to leave a WHILE ... WEND or a REPEAT ... 
UNTIL loop. 
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5.6 GOTO 


The GOTO statement can explicitly transfer control to another part of the program. 

This may sound like an extremely powerful feature to have in a programming language, and 
so it is. BASIC used to rely heavily on the use of GOTO (this is why BASIC is still regarded 
disdainfully by some programmers); however, structures like those described earlier have 
made the GOTO (and its first cousin, the GOSUB) all but obsolete. If you find you are using lots 
of GOTOs in a finished program you should think carefully about whether your program 
would be clearer if it were written with IF statements, 00 and FOR loops, and SUBs. 

For the times when you really need one, a GOTO statement is used quite straightforwardly: 
GOTO location 

You can only use GOTO to transfer control within the same part of a program, that is, you 
cannot use GOTO to enter or leave a SUB or FUNCTION. 



5.7 Stopping and Starting 


There are two statements that stop the program: ENDandSTOP. END stops the program just 
as if it had run out of program lines. It is mainly used to stop the program when it has Finished 
its intended tasks but there are more lines in the program. You must use an END statement at 
the end of your program if there are SUBs, FUNCTIONS, or IMPORT blocks which follow the 
end of the main routine. 

STOP stops the program and displays a message to that effect. STOP can be used to 
'breakpoint' a program while testing it, though the debugger's breakpointing facilities arc 
more versatile. See Chapter 4 of Part 1 for more information on debug points. 



END 

Use 

END is used to terminate execution of the program when it has completed its 
allotted tasks, as opposed to STOP, which is used in debugging. 

Syntax 

END 

Description 

END halts execution of the program immediately and unconditionally, it is 
compulsory to terminate the main program with an END statement before any 

SUBs or FUNCTIONS are defined. 

See also: 

STOP 
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GOTO 

GOTO is used to jump unconditionally to another part of the program. 

GOTO location 

GOTO may be spelt as two words thus: GO TO 

When a GOTO statement is executed, control passes unconditionally to the 
location referenced. GOTO can only divert control within the same part of the 
program; it is not possible to jump into orout of SUBs or FUNCTIONS. 


STOP 

Use STOP is used to halt the execution of the program in a condition where the 
variables can be inspected or altered. 

Syntax STOP 

Description STOP stops execution of the program immediately, and a message to that effect is 
displayed on the screen. 

See also: CONT, END 


Use 

Syntax 

Description 
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Programs of any complexity are easier to design, write, and maintain if the overall task is 
broken down into a number of separate sub-tasks of manageable size and complexity. This 
technique is known as 'decomposition' - a sort of divide and conquer. For example, a 
program to print an order might break down as: 


I- 

set up printer 


Task: print an order 

I-1- 

prepare process orders 

— J -1 i-r- 1 -1 

set up variables loop get o rder print order 

get name get amount construct text 


-1 

«y up 

print formfeed 

- 1 - 1 

check space print text 


Each sub-task represents a separate operation, which can be handled individually as a single 
instruction. Such an operation is known as a routine. 

Segmenting the program in this way has a number of advantages: 

• You can readily make the structure of the program reflect the structure of the task. This 
will make it easier to design and understand. 

• It allows you to write the program a bit at a time. Starting from the top, you write only 
one level down at a time, checking that each level works correctly before proceeding to 
the greater detail of the next level. This makes it easier to spot and correct errors, 
because you will always know the level they have developed on. 

• As each routine handles a separate sub-task of'manageable size and complexitythe 
instructions that go into each routine will be much easier to design, write and test than 
the instructions that solve the whole task. 

• Routines that handle a task that is carried out more than once or a range of similar tasks 
reduce the size of the program, because the same code can be called upon wherever a 
particular task needs to be carried out 

• Routines can also save on programming effort: once you have worked out the 
instructions needed to solve a particular sub-task, you can re-use this wherever you need 
this type of task to be carried out - including different programs. 

• Once the routines have been designed and tested, the final testing becomes a matter of 
making the various routines work together. 
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With routines carrying out the various sub-tasks, the program itself becomes naturally 
divided into the code for the main program, which calls the various routines in turn, and the 
code of the routines themselves. 

What a Routine is 

A routine is a part of a BASIC 2 Plus program which is written separately from the rest of the 
code. It can be thought of as a command or function similar to those provided by BASIC 2 
Plus, except that it is defined by you, the programmer, instead of by the authors of BASIC 2 
Plus. 

Like a BASIC 2 Plus command, a routine is invoked by means of a statement in the main 
program (or in another routine - or even in the same routine). Information which has to be 
passed in and out of the routine must be transferred explicitly by means of parameters and 
shared variables. Line-numbers, labels, and, in general, variables in the routine are quite 
separate from those in the rest of the program. 

In some ways BASIC 2 Plus's routines are similar to the subroutines (GOSUB-routines) 
implemented in most BASICS. But there are a number of important advantages which come 
from the way routines keep their variables separate: 

• The only'main program' variables that can be changed by a routine are ones specifically 
mentioned when the routine is called. All other variables (other than shared variables) 
are automatically independent. So any accidental duplication of variable names can't 
affect the values used by the main program or other routines. 

• It is possible to pass the value of a variable to a routine without changing the original 
value in the main program. 

• The job of matching up the variables used in the main program with the variables used in 
the routine is entirely handled in the statement that calls up the routine: there is no need 
to match these up by hand before the routine is called or to unpick the results afterwards. 

• When the execution of a routine is complete, memory occupied by the routine's variables 
('local variables') is reclaimed and can be used by other parts of the program. 

There are two sorts of routine: subprograms (or SUBs) and routine functions (often referred to 
simply as ’functions'). Subprograms carry out tasks to the user's specification. Functions 
calculate a result which can be used in other parts of the program. 

You should note that the standard terms used for these structures provide spectacular 
opportunities for confusion, especially since there is another structure, not dealt with until the 
end of this chapter, called a subroutine, which is not a routine at all! 
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6.1 Subprograms or SUBs 
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Syntax 


where 


Description 


A subprogram is declared using the statements SUB and END SUB. 

The simplest form, without parameters, is: 

SUB subprogram-name 
subprogram-body 
END SUB 

subprogram-name may be any name (though obviously there are restrictions to prevent it 
duplicating other names in the program). 

subprogram-body is a sequence of BASIC 2 Plus statements. It can include almost any 
instructions; specifically, it can include calls to other routines or even to itself (a routine 
which calls itself is termed recursive). A routine cannot, however, include other SUB or 
FUNCTION definitions, nor can it include DATA statements. 

All variables, arrays, locations etc. referred to within the subprogram are local to the 
subprogram (though variables and arrays can be explicitly shared - see Section 6.4). In 
particular, you can't refer to locations outside the subprogram. (There is one exception - the 
RESTORE statement - explained in Chapter 2.) 




SUB 

SUB is used to define a subprogram. 

SUB sub-identifier[( formal-list ) //EXPORT; 

sub-body : 

END SUB 

sub-identifierisaname. 

sub-body is a sequence of BASIC 2 Plus statements, separated with colons or new 
lines in the usual way. 

Note that SUB must be the first statement of the program line in which it appears. 

A SUB statement may never be executed directly; it must be invoked by means of 
a CALL statement. For the description of how this works, see CALL. 

If the word EXPORT is present in the statement, the subprogram can be exported 
to other program units. Otherwise it is restricted to the program unit In which it is 
declared. 
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Subprograms are put at the end of the main program, after the final END; (this prevents control 
from 'falling off the end' of the main program into the routine). Similarly, subprograms in a 
module are put at the end of the module body, after the END NODULE - see the next chapter 
for details. To execute the subprogram, just give its name, optionally preceded by the 
keyword CALL. 

For example, a database program might have a SUB like this, which would be used to display 
the text of a menu: 

SUB menu_text 

PRINT " Club Membership Database • Nain Menu " 

PRINT 

PRINT H 1> New Member" 

PRINT " 2> Delete Old Member" 

PRINT " 3> Amend Current Member Details" 

PRINT " 4> List Members" 

PRINT " 5> Save Data" 

PRINT " 6> Quit Program" 

END SUB 


The main program would then just use the word menu_text as a command on its own 
whenever the menu was to be displayed. Using a SUB in this way would make the structure of 
the main program much clearer than including the PRINT commands individually. 


CALL 

Use CALL is used to invoke a subprogram. 

’ 

Syntax [CALL]sub-identifier((]actual-parameter[, actual-parameter]...[)] 
where both parentheses must be present, or neither, 
and subJdentifier is a name corresponding to the sub-identifier of a SUB. 
actual-parameter is expression 

or general-variable 
or actual-array 

Description When a CALL statement is executed, the given SUB is invoked. 

The formallist of the SUB is processed against the actual-parameters in the CALL 
statement, according to the table Parameter Passing. 
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Parameter Passing 

Formal parameter 

VAL simple-var 
CONST simple-var 
VAR simple-var 
VAR formal-array 
ref simple-var 
ref simple-var 
ref formal-array 


Actual parameter Routine manipulates 


expression 

expression 

general-variable 

actual-array 


expression 

actual-array 


copy of expression's value 
copy of expression’s value 
actual parameter 
actual parameter 
actual parameter 
copy of expression's value 
actual parameter 


— 


1 


6.2 Parameters 

Routines are more useful when they can process information transferred from the main 
program; the most effective way to do this is through parameters. 

In the declaration part of a routine, a number of formal parameters can be declared. The 
simplest form of such a declaration is 

SUB routine-name(\l AL formal-parameter[, formal-parameter]...) 

routine-body 
END SUB 

which is then called by the statement 

/CALL ]routine-name ( actual-parameter /. actual-parameter ]...) 

formal-parameters following the keyword VAL are called value parameters; they must be 
simple variables (either string or numeric). The actual-parameters must be of the same number 
and type as the formal-parameters: they can be any expressions of the appropriate type. 

Whenever the subprogram is executed, the actual parameters are evaluated and the resulting 
values are assigned to the corresponding formal parameters. The routine-body is then 
executed. During execution, the formal parameters are treated as ordinary local variables; 
they may be read and assigned to in whatever way you want. Note, though, that assigning 
new values to the formal parameters has no effect on anything outside the subprogram. 
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For instance, consider the program: 
x-10 

CALL double_number(x) 

PRINT "We have just doubled ";x 
END 

SUB double_number(VAL number) 

PRINT "Twice ";number; 
number - 2 * number 
PRINT "Is ";number 
END SUB 

which will produce 

Twice 10 is 20 

We have just doubled 10 

It is also possible to prevent formal parameters being assigned to throughout the execution of 
the subprogram. To do this, replace the keyword VAL with CONST; the formal parameters will 
then be treated as constants throughout the execution of the SUB. 

6.2.1 VAR parameters 

With variable parameters (VAR parameters) the keyword VAL is replaced with VAR in the 
syntax: 

SUB routine-name (VAR formal-parameter]. formal-parameter]...) 

routine-body 
END SUB 

The difference in operation is that now any reference to a formal-parameter is taken as a 
reference to the actual-parameter itself; any changes made to the formal-parameters during the 
execution of the subprogram are reflected as changes to the corresponding actual-parameters: 
For instance, if we change the VAL parameter in our example to VAR: 

x-10 

CALL double_number(x) 

PRINT "The value of x Is now ";x 
END 
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SUB double_number(VAR number) 

PRINT "Twice "rnumber; 
number = number * 2 
PRINT "is ":number 
END SUB 

the output becomes 

Twice 10 is 20 

The value of X is now 20 

This puts different restrictions on the kind of object which can be used for formal and actual 
parameters. Since actual parameters may have their values changed by the subprogram, they 
must be general-variables or actual-arrays. 

An actual-array is an array variable (or a vector field in a record) followed optionally by a pair 
of empty array brackets, () or [ ]. 

If the actual parameter is a general-variable, the corresponding formal parameter must be a 
simple variable; if the actual parameter is an actual-array, the formal parameter must be a 
formal-array. The types of the formal and actual parameters must be the same (that is, both 
numeric or both string). 

A formal array is a variable which must be followed by a pair of array brackets. The brackets 
are empty in the case of a single-dimension array; for arrays of n dimensions, there must be 
n-1 commas inside the brackets. Note that this syntax means that the subprogram "knows' 
how many dimensions the array has, but does not need to 'know' its array bounds, or even the 
number of elements it contains. 

6.2.2 Reference parameters 

It is permitted (though not recommended) to omit the VAR, VAL or CONST from the formal 
parameter list In this case each parameter is either considered as a ref parameter, that is, it is 
treated asaVAR or VAL parameter according to the type of the actual parameter. If the actual 
parameter is a simple variable or a subscripted variable, then the formal parameter is treated 
as if it were preceded by VAR. In other cases (eg. if the actual parameter is a constant, an 
expression held within brackets, a substring, a record field or an actual array) then it is treated 
as if the formal parameter were preceded by VAL. 
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6.2.3 Mixing parameters 

It is possible to mix VAL, VAR, and CONST parameters in one function declaration. Simply 
follow each keyword with a list of formal parameters of that type, separated with commas: 

SUB sort(VAR array$[], 1ndex$[,), VAL low. high, 

CONST file_stream;file_size) 

If a group of formal parameters is preceded by a semicolon instead of a comma, they will be 
taken as ref parameters unless there is a new VAL, VAR, or CONST: 

Note that the actual parameters must always be separated with commas. 


6.3 Functions 

Routine functions are very similar to the subprograms defined in the previous section. The 
difference is that functions return a resulL 

A function is defined using the statements FUNCTION and END FUNCTION. Its form can be: 

FUNCTION function-name [( parameter-part)] 
function-body 
END FUNCTION 

(the parameter-part has exactly the same options and restrictions as the parameter part of a SUB 
declaration.) 

function-name may be any identifier (though as with subprograms there are restrictions to 
prevent it duplicating other identifiers in the program), and this identifier indicates the type of 
the result which will be returned (numeric or suing) in the usual way ($ as last character for 
string; otherwise numeric). 

Somewhere in the function body there will normally be one or more assignment statements 
with the function name on the left hand side. For example: 

FUNCTION discount! length_of_serv1ce ) 

SELECT CASE length_of_serv1ce 
CASE IS < 12 : discount - 0 
CASE 12 TO 24 : discount - 3 

CASE 24 TO 35 : discount - 7 

CASE 36 TO 47 : discount - 10 

CASE IS >- 48 : discount - 15 

END SELECT 
END FUNCTION 
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FUNCTION 

Use FUNCTION is used to define a routine function. 

Syntax FUNCTION function-identifier [ ( formal-list) // EXPORT ] 
function-body : 

END FUNCTION 

where function-identifier is identifier, 

function-body is a sequence of BASIC 2 Plus statements separated with colons or 
new lines in the usual way. 

Note that FUNCTION must be the first statement of the program line in which it 
appears. 

Description FUNCTION statements are never executed directly; they are invoked whenever 
the function-identifier is used as part of an expression. 

If the word EXPORT is present in the statement, the function can be exported to 
other program units. Otherwise the function is restricted to the program unit in 
which it is declared. 

routine-function-call 

Use The routine-function-call is used to invoke a routine function. It is not a BASIC 2 Plus 
statement in its own right; instead, the routine-function-call is used in expressions of 
the appropriate type. 

Syntax function-identifier[ ( ]actual-parameter[, actual-parameter}.:.[)] 

where both parentheses must be present, or neither 

function-identifier is a identifier corresponding to the function-identifier of a FUNCTION 
definition. 

Description When an expression containing a routine-function-call is evaluated, the function-body ol 
the corresponding FUNCTION is invoked. 

The formal-list of the FUNCT ION definition is processed against the actual-parameters 
according to the table Parameter Passing. 

A routine-function-call is a particular case of the general function-call defined in the list 
of conventions and definitions at the start of this book. 
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To use the function in the main program or another subprogram, its name is used exactly like 
any other expression of the appropriate type - numeric or a string: 

PRINT "Since you have been a member for years : 

PRINT " years, we can offer a discount of 
PRINT (discount! years ) / 100) * payment_due 

If no assignment is made to the function, it is treated like an undefined variable, namely the 
value returned will be 0 (for a numeric function) or the null suing (for a string function) 
unless OPTION TRAP is set, in which case an error is raised. 

If there is more than one statement which assigns a value to the function-identifier, the last of 
these statements to be executed defines the value relumed by the function. 


6.4 Other features of Routines 

6.4.1 Shared Variables 

Normally variables in different routines are considered distinct from each other and from 
variables in the main progam. The main communication between routines and their 
environment is by means of VAR parameters and function results. 

However, it is sometimes necessary to allow routines to access global variables used in other 
routines or in the main program. This can be done by declaring the variable as SHARED: 

SHARED shared-varf. shared-var]... 

The shared-vars can cither be simple variables or formal arrays, as explained earlier under 
VAR-paramctcrs. 

If the SHARED statement is in a routine, the shared variables are shared between that routine 
and the main program. Variables with the same name which are used in other routines are still 
regarded as distinct. 

If the SHARED statement is in the main program, the shared variables arc shared between the 
main program and all the routines. 
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SHARED 

Use 

SHARED makes global variables directly available to routines. 

Syntax 

SHARED shared-object [, shared-object]... 

where 

formal-var is simple-variable 


or array-identifier ( [ . / ... 
or array-identifier [ [, j... ] 

Description 

If the SHARED statement appears in a routine, occurrences of the specified 
variables in that routine refer to the global variables, not local variables with the ! 
same name. This does not affect variables in other routines. 


If the SHARED statement appears in the body of a program or module, 
occurrences of the shared variables in any routine refer to the global variables. 


6.4.2 Exiting prematurely 

Normally the statements in a routine body are executed sequentially until an END SUB or END 
FUNCTION is reached, at which point control is relumed to the calling routine. However, it is 
possible to return before the end of the routine body is reached; the statement which docs this 
is EXIT SUB or EXIT FUNCTION. 



EXIT SUB, EXIT FUNCTION 

Use 

EXIT SUB and EXIT FUNCTION are used to terminate a subprogram or routine 
function before the terminating END SUB or END FUNCTION is reached. 

Syntax 

EXIT SUB 

or 

EXIT FUNCTION 

Description 

When the appropriate EXIT statement is executed, control immediately passes 
back to the calling statement. Any assignments which have been made to the 
function identifier are returned as normal. 
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6.4.3 Recursion 


Routines can make calls to any other routines, irrespective of the order they are defined in. 
Specifically, it is possible for a routine to call itself; this is called recursion. For example, 
consider the following: 

n-0 

CALL recurse(n) 

ENO 

SUB recurse(VAL n) 

PRINT "Level ":n;" on the way up" 

IF n<3 THEN CALL recurse(n+l) 

PRINT "Level ":n;" on the way down" 

END SUB 

The output from this will be: 

Level 0 on the way up 
Level 1 on the way up 
Level 2 on the way up 
Level 3 on the way up 
Level 3 on the way down 
Level 2 on the way down 
Level 1 on the way down 
Level 0 on the way down 

When a routine is called recursively, each invocation will have its own set of variables quite 
distinct from the other invocations. 
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6.5 Subroutines & Expression functions 

Subprograms and routine functions are the most important ways of separating parts of a 
program from the main body of code. But BASIC 2 Plus also provides two other constructs, 
subroutines and expression functions. They are provided to keep BASIC 2 Plus compatible 
with other BASICS. Their use is not recommended in general; routines are more powerful 
and easier to debug. 

6.5.1 Subroutines 

A subroutine is a section of code invoked by a GOSUB statement as follows: 

GOSUB location 

where the location is a label or line number, exactly as for a GOTO. 

When BASIC 2 Plus executes a GOSUB, contol is temporarily diverted to the line referenced 
by the location. Statements are executed sequentially from that point until a RETURN statement 
is executed, whereupon control is transferred back to the statement following the GOSUB. 


It is an error to execute a RETURN if there is no GOSUB call in progress. 


GOSUB 

Use GOSUB is used to call a subroutine elsewhere in the same program body, module 



body or routine. 

Syntax 

GOSUB location 


GOSUB can be spelt as two words thus; GO SUB. 

Description 

GOSUB transfers control to the statement referenced by location. 

See also: 

RETURN 

Use 

RETURN 

RETURN is used to terminate a subroutine. 


Syntax RETURN 

Description When a RETURN statement is executed, control is passed to the statement 

following the most recently called GOSUB which is still active. A GOSUB remains 
active until it is returned to by means of a RETURN statement. 
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ON...GOSUB 

Use 

Like ON... GOTO, this statement is a relic from older BASICS, included to make 
BASIC 2 plus compatible. 

Syntax 

ON condition GOSUB / locationl][. [location2]}(. [location3 ]]... 

where 

condition is an integer-expression 

locationl, location, locations, ... etc are locations. 

GOSUB may be spelt as two words thus: GO SUB 

Description 

condition is evaluated, and if it evaluates to 1,2,3.BASIC 2 Plus executes the 

respective statement from among the statements GOSUB locationl, GOSUB \ocation2, 
GOSUB location3, .... provided that the necessary locations are listed. If they are 
not, control passes to the next statement without error. 

See Also: 

RETURN 


6.5.2 Expression functions 

Expression functions are user-defined functions which are defined with a single BASIC 2 
Plus statement. The syntax is: 

DEF function-name [( parameter[. parameter]...)]= expression 



The function-name has the same form as a variable name, and ends in a $ or not according to 
whether the expression function will return a string or a numeric value. 

The parameters can only be simple variables. 

Expression functions are called in exactly the same way as routine functions: the function 
name is used (with any necessary actual parameters in brackets) just like a variable or 
expression. For example, an expression function could be defined with the statement 

DEF dist( x . y ) = SQR( x * x + y * y ) 
and then called in a statement such as: 
radius - dist( 3, 4 ) 

All parameters arc passed by value, that is, like VAL parameters in routine functions. The 
actual parameter may be any expression of the appropriate type. 
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DEF 

Use 

DEF is used to define an expression function. 

Syntax 

DEF function-identifier [ ( parameter(, parameter ]...) J - result-expression 

where 

function-identifier is an identifier, and result-expression is an expression of the same type. 
Each parameter must be a simple-variable. 

Description 

DEF statements define an expression function; the function must be defined 
before the function-identifier is used in an expression. The same function-identifier may 
be defined more than once by separate DEF statements, but in each statement 
the number, types, and names of the parameters must be the same. 


expression-function-call 

Use 

The expression-function-call is used to invoke an expression function. It is not a 

BASIC 2 Plus statement in its own right;instead, the expression-function-call is used 
in expressions of the appropriate type. 

Syntax 

where 

function-identifier[ ( actual-parameter[, actual-parameter ]...) ] 
each actual-parameter is an expression. 

Description 

When an expression containing expression-function-call is evaluated, the result- 
expression of the corresponding DEF is evaluated, and the result is the value used 
for the value of function-identifier. 


When evaluating result-expression, the parameters in the DEF statement are replaced 
by the values of the corresponding actual-parameters in the expression-function-call. 


Any other (non-parameter) variables in the DEF statement take the values they 
hold at the time of the expression-function-call, not the values they hold at the time the 
DEF statement is executed. 


A routine-function-call is a particular case of the general function-call defined in the list 
of conventions and definitions at the start of this book. 


Note that expression functions must be defined in the main body of a program (or module); 
they cannot be defined inside a routine, though they can be called from a routine. The 
statement defining the function must be executed before the function itself is used. 

DEF can be used to redefine an existing expression function, but the new version must have 
an identical formal parameter list to the old version. 
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Chapter 7 

Modules 


One important feature introduced in BASIC 2 Plus is the concept of a module. A module is a 
section of code comprising a body and a collection of routines, any of which can be invoked 
by BASIC 2 Plus programs or by other modules. 

In many ways a module is like a subprogram. It cannot be executed alone, but can only be 
called from a main program or another module. It can have parameters - formal parameters, 
like a routine - which are matched with actual parameters in the calling program. And like a 
subprogram, these parameters can be VAR, VAL, CONST or ref parameters. 

In other ways it is like a main program. It has global variables which retain their value 
throughout the time that the module is held in memory. (This usually means until the main 
program has finished running.) A module can have its own DATA statements, which are read 
by READ statements within the module and its routines. The module is stored in its own file on 
disc, separate from any main programs which may call it; if it is not already held in memory 
it is read from disc when a main program executes a LOAD MODULE statement 

Modules are usually written in BASIC, but BASIC 2 Plus can also call modules written in 
machine code. This may be particularly useful if speed or memory constraints are tight 
Machine code modules are introduced in the last section of this chapter, and given in detail in 
Appendix IV. 

Global variables 

Perhaps the most important difference between a subprogram and a module is that a module 
can have its own global variables. These can only be accessed from within the module itself, 
but (unlike local variables in routines) their value is preserved for the next time you access 
the module. The values are only lost when the module is unloaded. 


Overlaying 


Another feature of modules can be used when a program is long and memory is short Since 
BASIC 2 Plus needs to keep the code for a module in memory only during the time the 
module is loaded, an UN LOAD MODU LE statement will free memory, which can then be used 
to store more data, or another module. 
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Libraries 
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Modules are not restricted to one program; they have a separate existence as program units in 
their own right. Because of this, a module (unlike a routine) can be used by more than one 
main program. 


It is also possible to collect together a group of routines which are useful in similar 
circumstances, and put them into one module, which can then be loaded at appropriate times. 


For example, if you had written a number of routines for solving a certain sort of complicated 
equation, then instead of including these routines in all of your programs you could collect 
the routines into one module and load that module from any program which needed it. Any of 
the routines would then be available for you to import into your main program. 


7.1 The Syntax of Modules 

The main body of a module is precisely analogous to a subprogram definition: 

MODULE module-name [ ( parameters ) ] 
module-body 
ENO MODULE 

module-body is a sequence of BASIC 2 Plus statements, parameters takes the same form as the 
formal parameter list in a SUB, namely a list of formal parameters separated with commas or 
semicolons and with each parameter optionally preceded by VAL, VAR, or CONST. 

The body of the module is followed by any routines. If the routines are only to be called from 
within the module, their syntax is identical to the syntax for routines in the main program. If 
the routines arc to be called from outside the module, the word EXPORT must be appended to 
the end of the routine's heading, as described in the last chapter. 

Example - a UFO stack 

As an example of the use of a module, consider a LIFO stack. This is a structure into which 
numbers can be 'pushed', and from which those numbers can later be 'popped'. The number 
which is popped is always the number on the stack which was most recently pushed there, 
whence the acronym LIFO: Last-In, First-Out. 

Such a stack cannot be neatly implemented using routines. Since the stack has to be 
preserved between pushes and pops, the stack structure itself cannot be a routine variable. It 
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MODULE 

Use 

MODULE is used to define a module - a program unit which may be accessed and 
used by a BASIC 2 Plus program. 

Syntax 

MODULE module-namel ( formal-list) ] 
module-body 

END MODULE 

where 

module-name is a name, 

■ 

module-body is a sequence of BASIC 2 statements, separated with colons or new 
lines in the usual way. 

Note 

The above syntax defines the body of a module. It may be followed by any 
number of SUB and FUNCTION definitions and IMPORT blocks. 


could be stored as an (array) variable in the main program, shared with the routines which do 
the pushing and popping; however, it is much better style to keep all the routines and 
variables together in one module. 

The module looks like this: 

MODULE lifo ( VAL stack_size ) 

DIM stack[ 1 to stack_size ] 

SHARED pointer . stack[] 
pointer - 0 
END MODULE 

SUB push ( VAL n ) EXPORT 
pointer = pointer + 1 
stack[ pointer ] - n 
END SUB 

FUNCTION pop EXPORT 

pop = stack[ pointer ] 
pointer = pointer - 1 
END FUNCTION 

(Obviously this could (and should) be termed if it were going to be used in practice; 
specifically, there should be some check when pushing that the stack has not overflowed.) 
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A few points are worth noting immediately: 

Since the variables poi nter and stack[ ] are defined in the module body, they will be 
preserved between each call of push and pop. Furthermore, because they are defined as 
SHARED, push and pop will indeed manipulate the global variables pointer and stack[ ], 
and will not create local variables with the same names. 

The stack pointer needs to be initialised, and the stack itself needs to be dimensioned before it 
can be used. Initialisation tasks like this are typically carried out in the module body, and this 
is how they are implemented in the example. 

Finally, note that none of the variables is accessible outside the module, and indeed it is not 
possible to export variables. As with routines, this has the advantage that it is not possible to 
corrupt the stack by accidentally duplicating variable names. 

Loading a Module 

Before a module can be used, it must first be loaded. This is done with the command 
LOAD MODULE module-name . filename 
module-name is the name of the module as specified in its MODULE statement. 

LOAD MODULE statements can be executed in the main program or in any other module which 
has already been loaded. Attempting to load a modulethat is already loaded has no effect. 

To extend our example, then, the loading statement in the main program could appear as 
LOAD MODULE llfo, "C:\BASIC\LIF0.M0D" 

Note: Where a module is stored alongside the main program in the same directory, there is no need 
to give the name of this directory explicitly in the LOAD MODULE statement. Instead, the 
PROG PATHS function may be used as follows: 

LOAD MODULE llfo. PROGPATHS + "LIFO.MOD" 
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LOAD MODULE 

Use 

LOAD MODULE is used to load a module into memory. 

Syntax 

LOAD MODULE module-name , filename 

where 

module-name is a name 

Description 

BASIC 2 Plus checkes whether there is in memory a module named module- 


identifier which was loaded from the DOS file filename. If the module is not currently 
in memory, it is loaded from filename and made available for the program to call. 


(If the file does not exist, or contains the wrong information, an error is raised.) 

If such a module is already resident in memory, it is not reloaded, but it is made 
available to the program. 


PROGPATH$ & PROGFILE$ 

Use 

These functions return the current file name of the main program. 

Syntax 

PR0GPATH$ 

PROGFILES 

Description 

The current file name of the main program is the name of the file to 
which it was last saved, or, if it has not been saved, the name of the file 
from which it was loaded, otherwise, if it has not been saved or loaded, 
nothing at all. 


PROGPATHJ returns the directory part of name. PROGFILES returns the 
final filename part. Note that PROGPATHS+PROGFI LE$ is the full name of 
the file. 
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Importing a Module 

A module body and its routines can only be used by another program unit if they are 
explicitly imported by means of an import block. Similarly, modules can use the main 
program's routines only if they are imported. The import block has the following form: 

IMPORT ( MODULE module-name [ ( dummy-parameter-list ) ] ] 
routines-lo-import 
END IMPORT 

The first line consists only of the word IMPORT when the block is used to import routines 
from the main program into a module. 

The dummy-parameter-list has the same syntax as a formal-parameter-list. It can be a copy of the 
parameter list of the module. However, it is only used for type checking, that is, it enables 
BASIC 2 Plus to check that the parameters supplied to the module are of the correct type - 
string, numeric or array. Because of this, it is not essential that the names of the parameters 
correspond to either the actual or the formal parameters. 

routines-to-import is a list of the headings of all the routines which are to be imported. (This 
does not include the word EXPORT at the end.) A parameter list must be included if the routine 
takes parameters; as with the module heading, this is a dummy parameter list, included only 
for type checking. The names used for the parameters are irrelevant. 

Continuing the LIFO example, then, the import block looks like this: 

IMPORT MODULE lifo ( VAL stack.size ) 

SUB push ( VAL n ) 

FUNCTION pop 
END IMPORT 

The import block is put at the end of the program unit, after the final E NO. It can come before, 
after, or between the program unit's own routines. 

Calling a Module 

Calling a module is similar to calling a subprogram. The syntax is 
CALL MODULE module-name [ ( actual-parameters ) ] 

(Note that the keyword CALL is compulsory, unlike the CALL in a statement to call a 
subprogram.) 
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IMPORT 

Use 

An IMPORT block is used to specify the routines, constants and variables which 
are imported into one program unit from another. 

Syntax 

IMPORT [MODULE module-name [ ( formal-list ) ] ]: 

(import-declaration : ]... 

END IMPORT 

where 

module-name is a name, 

import-declaration is SUB sub-name [ ( formal-list ) ] 


or FUNCTION function-identifier [ ( formal-list ) ] 
or DECLARE CONST simple-var-list 
or D E C LA R E formal-var-list 


formal-var-list is formal-var [ , formal-var ] ... 
formal-var is identifier or formal-array 


Note: the IMPORT statement must appear before anything else on its line. Also 
note that, in common with other formal descriptions of syntax, new lines are used 
to make sure the syntax is unambiguous: where a new line or other statement 
separator is requred by the language, a colon is used in the syntax definition. 

Description 

Everything declared in the import-declarations is made available to the program unit 
in which the IMPORT block is situated. It must also be explicitly exported from the 
program units in which it is defined, or an error will be raised. 


r 


DECLARE CONST 

Use DECLARE CONST declares named constants. 

Syntax DECLARE CONST simple-variable (. simple-variable ]... 
Description In an IMPORT block DECLARE CONST imports named constants. 
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CALL MODULE 

Use 

CALL MODULE invokes the body of a module. 

Syntax 

where 

CALL MODULE module-name[(actual-parameter[, actual-parameter]...) ] 

actual-parameter is expression 

or general-variable 
or actual-array 

Description 

When a CALL MODULE statement is executed, the body of the module module- 
name is invoked. 


The formal-list of the module is processed against the actual-list of the CALL 
statement, according to the table Parameter Passing at the start of Chapter 6. 


EXIT MODULE 

Use 

EXIT MODULE is used to leave a module before the final END MODULE 
statement. 

Syntax 

EXIT MODULE 

Description 

When EXIT MODULE is called, control is immediately transferred to the statement 
following the CALL MODULE statement which invoked the module. 


Calling a module executes the module body. As noted above, this is commonly used to 
initialise any variables used in the routines. A module can be called from any program unit 
which imports it (not just the one it was loaded from). 

There is a special restriction on the actual parameters in a CALL MODULE statement. If the 
formal parameters are VAR or ref parameters, the actual parameters must be global variables 
defined in the main program body. They cannot be defined in any other module, nor can they 
be local variables. 

This restriction does not apply to routines defined in a module - only to the module body. 

Correponding to EXIT SUB and EXIT FUNCTION, there is an EXIT MODULE statement 
which may be used ifthe module body is to be exited before the final END MODULE statement. 
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Calling a Module's Routines 

Provided the import and export declarations have been made properly (as explained above) 
calling a routine in a module is exactly the same as calling one within a program unit So the 
main program in the LIFO example might appear as 

LOAD MODULE lifo, "C:\BASIC\LIF0.M0D" 

CALL MODULE lifo(lOO) 
push(98.4) 
z - pop 
END 



IMPORT MODULE lifo( VAL stack_size ) 

SUB push ( VAL n ) 

FUNCTION pop 
END IMPORT 

A module body can only be called once, whereas its routines can be called as often as 
necessary. 

Exporting Variables and Constants 

Normally, variables and constants declared in different program units are regarded as 
distinct. But it is possible to export variables from the main program to any of its modules. 
However the reverse is not true: global variables in modules cannot be exported. And local 
variables can never be directly exported (though they can be passed as parameters). 

The syntax for exporting global variables is 
EXPORT variables 

in the body of the main program. ( variables is a list of simple-variables and formal-arrays 
separated by commas.) 



EXPORT 

■ ■ ■ 

Use EXPORT is used to make a main program's global variables available to any 
modules it calls. 

' : ' • 

Syntax EXPORT export-object[. export-object]... 

where export-object is single-variable 

or array-identifier ((.]... ) 
or array-identifier [/,)...] 
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To import them into a module, include a DECLARE statement in the import block of the 
module where they are imported: 

DECLARE l CONST ] variables 

CONST must be included if a constant is imported, and in this case variables can only contain 
simple variables, not formal arrays. 


Unloading Modules 

It is not usually necessary to unload a module unless memory is short, or the program exceeds 
the limit of nine modules loaded at once. 

On occasions when it is necessary, the syntax of the command is (unsurprisingly) 

UNLOAD MODULE module-name 

A module cannot be unloaded if any of its routines are active, that is, if they have been 
initiated but their END or EX IT statement has not yet been executed. 
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7.2 Modules on disc & in memory 

When a LOAD statement is executed, BASIC 2 Plus checks both the module name and the file 
name to see if the module is already in store. If both names correspond to the names of a 
module already in the computer’s memory, that is the module which is used by the program. 
Otherwise the module will be loaded afresh from disc. 





Every time a program is run, you will be asked if you wish to save any modified modules to 
disc. If you choose not to save, the edited version of the module will still be used. The option 
of saving is just to ensure the safety of your work. 



Sometimes, however, if memory is short, a module which has been saved to disc will be 
removed from memory. Modules are never removed while they are in use -that is, they are 
never removed while a program is rurtning if they have been loaded (with a LOAD statement) 
but not unloaded - and they are only ever removed if they have not been altered since they 
were last saved to disc. 

Since modules are removed without any kind of message being displayed, you should not 
change the floppy disc in your machine at a time when memory is short and BASIC 2 Plus 
could be silently creating more space by removing modules. 


If you only use a hard disc, this need not concern you particularly. However, you should be 
aware that BASIC 2 Plus works in this way so you won’t be surprised if the disc drive starts 
up for no apparent reason. 



7.3 Machine code modules 

BASIC 2 Plus supports modules written directly in machine code, as well as modules in 
BASIC. 

The syntax for calling a machine code module is exactly the same as the syntax for calling a 
BASIC module. So if you are given a ready-made module, it need not concern you whether it 
is written in BASIC 2 Plus or machine code - the only information you need is the code 
included in the import block. 



Appendix IV describes the format of a machine code module, and explains how it can be 
called from a program unit written in BASIC. 
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Chapter 8 

^ Streams 



Almost all input and output in BASIC 2 Plus is handled through data streams, generally 
abbreviated to 'streams'. This chapter gives a full explanation of streams and how they work: 
it describes what they are, why they arc so versatile, and how they are connected to the 
various input and output devices which can be accessed through BASIC 2 Plus programs. 
The actual commands which input and output data to the streams are not described here; they 
are explained over the next few chapters. 

What Streams Are 

Data streams are the link by which a BASIC 2 Plus program is connected to things such as 
printers, disc files, graphics plotters, the keyboard, and the screen, known collectively as 
input/output devices, or just 'devices'. Before a program can input or output data to a device, 
the device must be connected to an available stream. This is described as 'opening the device 
on the stream'. From then on, until the stream is closed again, all commands are addressed to 
the stream, not to the specific device. 

The advantages of this are considerable. To begin with, it makes input and output extremely 
versatile. The differences between one device and another (a printer and a text file, for 
example) are entirely coped with when the stream is opened, and thereafter it is only 
necessary to make sure that any input/output commands used are appropriate to the type of 
device connected to the stream. 


j—ef; 



It also makes it easy to switch to a different device: it is just a matter of changing one line of 
the program so that it opens the new device on the same stream. All the other statements in 
the program can stay unchanged, since they transfer data via a specific stream, not a specific 
device. 
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8.1 Opening devices on streams 

To open a device on a stream, use an OPEN statement. This takes the form 
OPEN ^ stream-number device-description 

The format of device-description depends on whether the device being opened is a sequential 
device, a graphics device, a window, or a random file. Each of these types of device is 
explained in a separate paragraph below. 

There are 16 streams available, numbered from 0 to 15. A stream can only be connected to 
one device at a time, (though a device can be open on more than one stream). Normally a 
program will only use one or two streams; in this case it can open devices on (say) streams #5 
and #6. 

However, if many streams are likely to be open at once the function FRE EFILE can be used; 
it returns the number of the next available stream, or -1 if no streams are available. 

To change the device a particular stream is connected to, you must close the stream and re¬ 
open it for its new use. 

Sequential Input and Output 

'Sequential input and output' describes devices which transfer data as a continuous flow of 
text characters. The term 'sequential' means that they have to take the characters in a set order 
- they cannot skip about and re-read or erase characters which have already been transferred. 
The typical sequential device is the printer, but BASIC 2 Plus treats text files and 
communications links as sequential devices too. (There is another kind of file - the Random 
file - which is very different, and definitely not a sequential device.) 



To open a printer on a stream, the command is 
OPEN It stream-number PRINT printer-number 

A printer-number of 0 specifies the standard printer, PRN; 1 to 3 specifies LPT1 - LPT3; 4 to 5 
specifies COM1 - COM2. PRN is also assumed if printer-number is omitted. 

(If output is directed to stream 0 without opening it, BASIC 2 Plus automatically opens the 
standard printer PRN on that stream. This saves having to worry about opening streams when 
writing simple and straightforward programs.) 
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OPEN 

Use OPEN associates a given stream with a device or file. 

Syntax OPEN [[[[stream-number [.] WINDOW window-number 

or OPEN [[[Jstream-number [,] INPUT filename [[.] LOCK lock-type] 
or OPEN [[[[stream-number [,] [exist] OUTPUT filename [[,] LOCK lock-type] 

or OPEN [[[[stream-number [,] [exist] APPEND filename [[,] LOCK lock-type] 

or OPEN [[[[stream-number [,] [exist] RANDOM random-spec [[,] LOCK lock-type] 

or OPEN [[[[stream-number [,] [exist] GRAPHICS filename graphics-spec 

or OPEN [[[Jstream-number [,] PRINT [printer-number] 
or OPEN [[[Jstream-number [.] DEVICE device-number 

Description Each of these different forms of the OPEN statement associate the given stream 
with a device or file. All other input, output and related operations use stream 
numbers to refer, indirectly, to the then open device or file. The CLOSE statement 
performs any tidying up required and undoes the association - "freeing" the 
stream. It is an error to attempt to open something on a stream which is in use. 

Files and devices are classified as : 

Screens, of two types: Text Screens and Graphics Screens 
Files, of four types: Input, Output, Random and Keyed Files 
Graphics Devices 
Simple Printers 

This classification carries over to streams. Operations on streams are affected by 
the class of the stream. Some operations are illegal on streams of the wrong 
class. Some operations are ignored by some classes of stream. The effect of 
some operations is influenced by the class of stream. 

For a detailed description of each OPEN statement, and the resulting class of 
stream, see the relevant box below. 

FREEFILE 

Use FREEFILE is a function which returns on unused stream number. 

Syntax FREEFILE 

Description FREEFILE returns the number of the lowest numbered unused stream whose 
number is greater than 2. If all such streams are in use -1 is returned. 
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Input and output to text files is handled in exactly the same way. The syntax here is one of the 
following: 

OPEN ft stream-number INPUT filename-expression 

OPEN ft stream-number [qualifier] OUTPUT filename-expression 

OPEN ft stream-number [qualifier] APPEND filename-expression 

INPUT is used when the program is going to read from the file, OUTPUT is used if the program 
is going to write to the file afresh, and APPEND is used if the program is going to append to an 
existing file. 

When you open a file for INPUT, the file must already exist or an error will result You can 
also use the function FINDS to check for the existence of a file before opening it (see Chapter 
IS Tile handling*). 

Normally, when opening a file for OUTPUT, any file with that name will be deleted. Similarly, 
when opening a file with APPEND mode, it will be added to if it exists, or created if it does not 

However, an optional qualifier (NEW or OLD) can be used with OUTPUT or APPEND to police 
this, as follows: 

NEW - the file must not exist already and is created 
OLD - the file must exist already 

The most useful combinations of qualifier and mode are: 

NEW OUTPUT - to ensure that the file created does not already exist 
OLD APPEND - to ensure that the file being added to does already exist 

You should close any open files on a disc before you remove the disc from its drive 

Communication links are treated exactly like files; the only change is that the DOS port name 
replaces the file name. For example: 

OPEN ftS INPUT "C0M1” 

Communications links can, of course, be open for input and output at the same time, but they 
must be opened on different streams. So the above example would probably be accompanied 
by 

OPEN ft6 OUTPUT "C0M1" 


APPEND is not used for communications links. 






Chapter 8: Streams 


OPEN...PRINT 

Use OPEN... PRINT associates a given stream with a simple printer device. This 
opens a stream of Simple Printer class. 

Syntax OPEN [][Jstream-number [,] PRINT [printer-number] 

where print-number is an integer-expression, giving a value in the range 0..5 : 

0 = PRN 

1..3 = LPT1 to LPT3 

4. .5 = COM1 to COM2 

Description This statement opens a simple printer device for simple text, sequential output. If 
print-number is omitted then 0 is assumed. 

OPEN...INPUT 

Use OPEN file for input. This opens a stream of Input File class. 

Syntax OPEN [][]stream-number [,] INPUT filename [[,] LOCK lock-type] 

Description The given file is opened for input on the given stream. The file may be read 
sequentially. The file is assumed to be a simple text file. 

If no lock is specified the file is opened read locked. 

OPEN...OUTPUT & OPEN...APPEND 

Use OPEN file for output. This opens a stream of Output File class. 

Syntax OPEN / ]]]stream-number [,] [exist] OUTPUT filename [[,] LOCK lock-type] 

OPEN [ifjstream-number [,] [exist] APPEND filename ([,] LOCK lock-type] 

where exist isNEWorOLD 

Description Both of these statements open files for simple text, sequential output. If the file 
specified already exists then 0PEN_0UTPUT empties it, while OPEN-APPEND 
arranges that the output is added at the end of the file. If the file does not exist, 
then both statements create a new, empty, file of the given name. 

If the NEW exist option is present then the file must not exist. If the OLD exist option 
is present then the file must exist. 

If no lock is specified the file is opened write locked. 
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Graphics 


Windows 


To open a graphics device (such as a plotter or a bit image printer) you use the command 

OPEN It stream-number DEVICE GEM-device-number 


GEM-device-numberis an integer expression in the range 1 - 60 specifying the device number. 
The device numbers which may be used are: 


Device number 
11-20 
21-30 
41-50 


Device description 
plotters 
printers 
camera 


Graphics can also be sent to a special kind of disc file called a metafile, which can then be 
used by other programs, or printed directly. To open a metafile, the command is: 

OPEN If stream-number GRAPHICS filename-expression 


Windows are slightly more complicated for two reasons: firstly, a window can be opened as a 
graphics device or as a text device, and secondly, because two windows (numbers 1 and 2) 
arc opened automatically in appropriate circumstances. 

GEM provides four windows, any or all of which can be displayed on the computer's screen 
at any one time. As you have seen, all four are on view when you load BASIC 2 Plus. 
Windows 3 and 4 are used for Edit and Dialogue respectively. Windows 1 and 2 are not 
initially used for anything. None of the four is open on a stream. (This is different from 
BASIC 2 Plus’s predecessor, BASIC 2.) 

If you direct output to stream 1, window 1 is automatically opened for you on that stream; 
likewise, if you direct output to stream 2, window 2 is automatically opened on stream 2. 
(This assumes that you have not opened the windows on other streams, or connected those 
streams to any other device.) 

To explicitly open a window on a stream, use the command: 

OPEN If stream-number WINDOW window-number 

This does not, in itself, make the window visible on the computer’s screen; to do this, execute 
the statement: 

WINDOW # stream-number OPEN 

(See Chapter 14 for more details.) 
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OPEN...GRAPHICS & OPEN...DEVICE 

Use These forms of OPEN associate a given stream with a graphics device or a 
Metafile. Both forms open a stream of Graphics Device class. 

Syntax OPEN [tfjstream-number [,] DEVICE device-number 

OPEN ^]$tream-number [,) [exist] GRAPHICS filename graphics-spec 

where exist \s NEW or OLD 

device-number is an integer-expression, giving a value in the range 0..32767. 
graphics-spec \s [[,] SIZE m-width, m-height] [[,] SPACE p-width[.p-height]J 
m-width and m-height are numeric-expressions, giving positive, non-zero, values. 
p-width and p-height are integer-expressions, giving values in the range 1 ..32768. 

Description The OPEN-DEVICE statement opens the given device. For the meaning of the 
device-number see your GEM documentation. Typically Device 21 is a printer - so 
opening device 21 allows direct graphics output to the printer. 

The OPEN-GRAPHICS statement opens the given file as a GEM Metafile. A 
Metafile is like a GEM device, but graphics output is stored in the file. This file 
may later be printed, or may be used by other GEM applications. If the NEW exist 
option is present then the file must not exist. If the OLD exist option is present then 
the file must exist. 

To output graphics BASIC 2 Plus needs to know the actual size of the drawing 
surface. For real devices this information is provided by GEM. For Metafiles the 
size may be specified in the SIZE clause - the m-width and m-height values give the 
width and height of the drawing surface in metres (which when multiplied by 
10,000 and rounded to integer must be values in the range 1 ..32767). If no size 
is given then a width and height equivalent to a full size graphics screen are 
assumed. 

To output graphics BASIC 2 Plus also needs to know the size of the drawing 
surface in device "pixels". For real devices this information is provided by GEM. 
For Metafiles this size may be specified in theSPACE clause. If no size is given 
the device is assumed to be 5000 pixels along its shorter side, with square pixels 
- which is the same as the default User Space. This should suffice unless the 
size in device pixels is known and is material, or if a finer resolution is required. If 
the size is given then p-width and p-height are the width and height in pixels - it the 
p-height is omitted then the device is assumed to be p-width pixels along the shorter 
size, with square pixels. 
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Windows 3 and 4 are used for Edit and Dialogue respectively. If you open them to streams, 
they will be displayed as Results-3 and Results-4, and the Edit information and the Dialogue 
information will disappear from view. However, as soon as BASIC 2 Plus displays the Edit 
and Dialogue information the contents of Results-3 and Results-4 will be lost Note that you 
can only open streams to Windows 3 and 4 from within a program; you cannot use these 
windows from the Dialogue window. 

Windows can be defined as graphics devices or as text devices. Graphics devices can display 
text as well as graphics, and they can display it in more ways than text windows can. But in 
certain circumstances graphics windows are slower than text, and they can store fewer 
characters than text windows. (There are differences, too, in the way they handle wrap¬ 
around of text. For details, see the appropriate sections of Chapter 9.) 



Results-1 is a graphics window by default The other three are text windows by default. To 
change this, again see the appropriate sections of Chapter 9. 



A window cannot be open on more than one stream at once. 


OPEN...WINDOW 

Use OPEN-WINDOW associates a given stream with a screen window. 

Syntax OPEN Upstream-number [,) WINDOW window-number 
where window-number is an integer-expression, giving a value in the range 1..4. 

Description BASIC 2 Plus provides four screen windows, numbered 1..4, called Results-1 to 
Results-4. A window may be open on only one stream. 

A window is both an object on the actual screen and a window onto a "virtual 
screen". The operations which move a window, change its size, etc. are acting on 
the window object. The operations which write characters, draw lines, etc. are 
acting on the virtual screen, part or all of which is visible through the window. 

The stream will be of class Graphics Screen or Text Screen, depending on the 
class of the virtual screen. The SCREEN statement may be used to change the 
attributes and class of the virtual screen. 

Windows 1 and 2 are freely available. Window 1 is initialised as a Graphics 
Screen, Window 2 as a text screen. It is not, in fact, necessary to open these 
windows, simply using Stream 1 implicitly opens Window 1 and the same applies 
to Stream 2 and Window 2 (unless the relevent Window is already open on 
another stream. 



142 










Chapter 8: Streams 


Random and Keyed Files 

There are so many esoteric options when opening a Random or Keyed file that no description 
is given here: the complete description is given in Chapter 13 which deals exclusively with 
Random and Keyed files. 


8.2 The default stream 

In the absence of a stream number, BASIC 2 Plus uses the default stream. This is initially 
stream number 1, which, if unattached, causes BASIC 2 Plus to automatically open the 
Results-1 window. So simple programs need not use the OPEN statement at all, and need not 
direct output to a specific stream: instead, input and output statements can be left without a 
stream number, and the data will be sent to Results-1 automatically. 

If you want to change the default stream, use the STREAM command: 

STREAM if stream-number 

This makes the specified stream the new default stream. 



Use 

STREAM 

The STREAM statement changes the default stream. The STREAM function returns 
the current stream. 

Syntax 

: - Statement 

STREAM [ifjstream-number 

Syntax - Function 

STREAM 



Description 

For statements which act on streams the "current stream" is set to the stream 
specified or to the "default stream" otherwise. It is the "current stream" which is 
then operated on. For statements which do not act on streams the "current 
stream” is set to the "default stream". 

The initial "default stream" is 1. The STREAM statement sets the "default stream". 

When a function (built-in or user) is executed the "current stream" becomes the 
"default stream" for the duration of the function. 

The STREAM function returns the number of the "default stream" at the time. 
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Use C LOS E closes streams. 

Syntax CLOSE 

or C LOSE /#/ stream-number(, (^stream-number...] 

Description C LOS E with no parameters closes all streams which are associated with files. 
CLOSE with parameters closes the streams specified. Closing a stream 
completes any outstanding operations (for example writing any buffered data) and 
then frees the stream. 

It is not an error to close a stream which is not in use. 


8.3 Closing a stream 

When you have finished with a stream, it is good practice to close it using the statement 
CLOSE. This is particularly important for streams which have been connected to disc files. It: 

• ensures that all information written to the file (if opened for output/appending) has 
actually been transferred to it 

• allows the file to be opened again 

• frees that stream for re-use 

The syntax of the CLOSE statement is: 

CLOSE 

or CLOSE # stream-number [, if stream-number...] 

The first form closes all streams that are open. The second form closes the specified streams. 
All open streams are also closed automatically on exit from BASIC 2 Plus. 
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Text & Graphics Screens 


When using BASIC 2 Plus, output to the screen is handled as four different 'virtual' screens, 
each of which acts like a separate output device, though they all use the one physical screen 
connected to the computer. 

Each virtual screen is treated as a separate device, and so before it can be used it must be 
opened on a separate stream (see Chapter 8). When text or graphics is output to the display, it 
is stored in and formatted to fit the virtual screen used. 

Each virtual screen has a window corresponding to one of GEM'S windows on the real 
display. 

The window is usually smaller than the virtual screen. It reveals only part of the contents of 
its virtual screen, and can be scrolled to reveal different parts of the virtual screen, changed in 
size, made invisible (closed) or visible again (opened), moved to different parts of the 
computer's display, etc. The window serves as a peephole onto the virtual screen, limiting 
and framing the view. 
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Types of virtual screen 

There are two types of virtual screen: graphics screens, which can display text and graphics, 
and text screens, which can only display text The differences can be summarised as follows: 

A graphics screen provides a variety of text fonts, a variety of text sizes, angled text, 
automatic indentation, write modes (replacing or writing over text and graphics already on 
the screen) and graphics. However, it has fewer editing facilities and can hold less text. A text 
screen can store more text, has more editing facilities, and is handled more quickly. 



While a graphics screen allows you to produce more attractive displays, cither type of screen 

will do for normal text output, although text screens have the advantages of greater speed and - • * ’• 

text capacity. 


Flexible Screens 


There is one other difference you will notice if you print out very long lines of text. If a 
graphics window is narrower than its virtual screen, long lines of text may disappear out of 
view, as illustrated in the picture above. To view the end of the line, it is necessary to scroll 
the window. 



But text screens can optionally be made flexible (in fact, Results-2, -3, and -4 are flexible by 
default). The width of a flexible screen is automatically adjusted so that its entire width is 
always visible in the window. 

If the window is made narrower, the screen automatically becomes narrower too, and any 
characters which no longer fit within the right-hand margin are pushed onto the next line. If 
the window is made wider again, the screen becomes wider, too, and the characters move 
back to the right-hand end of the previous line. 

You can try this for yourself. Set up a variable 1 ong$ containing a very long string - about 
sixty characters - and scroll windows Results-1 and Results-2 until each of them is about half 
the width of your computer's screen. Then execute the statements 

print #1 . long* 
print #2 . long* 

When 1 ong* is printed to stream #1, you will just see the first part of the string appear in the 
window Results-1. Since the virtual screen is wider than its window, the end of the string will 
be on the virtual screen but outside the window, and you will have to move the scroll bars to 
see it. 
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When long* is printed to stream #2, you will see all of the string in the window Results-2, 
wrapped round across two lines. This is because the screen, being flexible, is exactly as wide 
as the window, and so when the string is wrapped onto the second line of the screen, it 
remains on view in the window. 

If you now scroll the window to adjust its width, you will make corresponding adjustments to 
the width of the screen, and 1 ong$ will always be displayed with as much of its length as 
possible on the first line, and the rest on the second line. 

The standard streams, screens and windows 

When you enter BASIC 2 Plus, it sets up four virtual screens numbered 1 to 4. They are 
initially as follows: 


Screen 

Screen 

name 

Type 

1 

Results-1 

graphics 

2 

Results-2 

text 

3 

Edit 

text 

4 

Dialogue 

text 


The first two screens are reserved for use by your programs and will suffice for most needs. 
You can also use the other two for your output (they will be renamed Results-3 and Results- 
4 when you do) but their main use is in Direct mode, for the Dialogue and Edit windows. As 
a result, any output in Results-4 will be lost when BASIC 2 Plus sends text to the Dialogue 
window, while any output in Results-3 will be lost when you use the Editor. 

Screens 1 and 2 are automatically opened if you direct output to stream 1 or 2 without 
opening it. Screens 3 and 4 are not automatically associated with a stream. Before you can 
send output to either of them, you will have to open them on a stream. This can only be done 
from within a program, not from the Dialogue window. 

All four virtual screens are set up for you when you enter BASIC 2 Plus. If you need to 
redefine them - for example, to produce four graphics screens, or screens of particular sizes - 
you should use the SCREEN command, as described here. 
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9.1 Redefining virtual screens 


When you redefine a virtual screen, the characteristics you can specify are: 

whether the screen is a text screen or a graphics screen 

its dimensions and how these relate to the size of the window used with this screen 

the size of the steps in which the window size can be changed, and 

whether an information line is displayed 

Different commands are used to define a screen as a text screen or as a graphics screen, so the 
details are given in separate sections below. 

Note that the screen must be open on a stream before you can redefine it. 

All four screens will return to the default definitions when you use the CLEAR RESET 
command. In addition. Screens 3 and 4 are reset when BASIC 2 Plus uses them as the Edit or 
the Dialogue screen. 


9.1.1 Defining a text screen 





To define a text screen, use the SCREEN TEXT command: 

SCREEN [ tistream-number ] TEXT [dimensions ] [options] 

dimensions can simply be FLEXIBLE if you wish to define a flexible screen which keeps the 
same width as its window. The height of a flexible screen is automatically adjusted too, in 
inverse proportion to the width: ie. the capacity of the whole screen remains constant at 4k 
(that is, 4096) characters. 


Alternatively dimensions can be width [FIXED ]. height [ FIXED /where width and height arc 
integer-expressions specifying the virtual screen dimensions, in columns and lines. They 
cannot specify a screen with a greater capacity than 4k characters; that is, width * height must 
be at most 4096. If FIXED is appended, that dimension of the window is forced to the same as 
the virtual screen. 

If dimensions is omitted from the command, the screen is defined so that when the window is 
open to its greatest extent, the whole of the virtual screen is visible. 

There are four possible options; they can be used in any order or combination, and they arc all 
optional. They may be separated with commas, but this is not essential. 
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SCREEN 

Use SCREEN sets the type and size of a Virtual Screen 

Syntax SCREEN fit stream-number [,]] GRAPHICS / size] ([,] window-attribute...] 

SCREEN $ stream-number [,]] TEXT [size] ([,] window-attribute...] 

SCREEN []]stream-number [,]] TEXT FLEXIBLE [[,] window-attribute...] 

where size \s width [FIXED], height [FIXED] 

window-attribute is: MAXIMUM width, height 
or:MINIMUM width, height 
or: UNIT width, height 
or: INFORMATION truth-value 

width and height are integer-expressions, giving positive, non-zero values. 

Description SCREEN-GRAPHICS sets the virtual screen to be a Graphics Screen. If no size is 
given, the size of the virtual screen is set so that all of it is visible if the window is 
at its maximum size. If a size is given, the width and height specify the size of the 
virtual screen in actual screen pixels, and must be values in the range 1..4096. 

SCREEN-TEXT sets the virtual screen to be a Text Screen. If no size is given, the 
size of the virtual screen is set so that all of it is visible if the window is at its 
maximum size. If a size is given, the width and height specify the size of the virtual 
screen in characters and lines, and which when multiplied together must give a 
value in the range 1 ..4096. The optional FIXED qualifier specifies that the window 
is to be of fixed size in that dimension - if necessary the size of the virtual screen 
in that dimension is reduced so that the window will fit on the actual screen. 

SCREEN-TEXT-FLEXIBLE sets the virtual screen to be aText Screen. With a 
flexible text screen the width of the virtual screen at any time is the same as the 
width of the window. The height of the virtual screen is the maximum possible 
given that the width multiplied by the height may be at most 4096 at any time. 

Each window-attribute sets a limit on the size of the window. MINIMUM and MAXIMUM 
contrain the window size. UNIT constrains the window size to be a multiple of the 
given units. For Graphics Screens these values are given in actual screen pixels. 
For Text Screens these value are in characters and lines. INFORMATION enables 
the "information line" at the top of the window - if the truth-value gives TRUE - 
which affects the maximum window height. It is because there is some interaction 
between window size and virtual screen size that these attributes are specified in 
this statement - rather than in separate WINDOW statements. 
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UNI T tv , ft (where tv and ftare integer-expressions) specifies the units by which the width and 
height of the window size will be allowed to change. The width is specified in character 
columns and the height in character lines. If omitted, this defaults to one column and one row. 

INFORMATION is followed by ON or OFF (or, equivalently, any Boolean expression). ON (ora 
non-zero value, or a true condition) specifies that the window will appear with an information 
line below the title bar. OFF (or 0, or a false condition) specifies that there is to be no 
information line. 


1 


SS3 






MINIMUM w . ft and MAXIMUM w . ft (where wand ftare integer-expressions) specify a minimum 
and maximum width and height for the window, in columns and lines. If omitted, these limits 
default to give approximately 18 columns and 6 lines (minimum) and the maximum size 
permitted on the display, respectively. 

If the window is open, it is made the top window. 

9.1.2 Defining a graphics screen 

To define or redefine a graphics screen, use the SCREEN GRAPHICS command: 

SCREEN [ Ostream-number ] GRAPHICS [ dimensions ][ options ] 

If dimensions is omitted from the command, the screen is defined so that when the window is 
open to its greatest extent, the whole of the virtual screen is visible. 



If dimensions is included, it takes one of two forms. To define the width and height of the the 
virtual screen in pixels, dimensions should be width ( FIXEO ], height [FIXED ] width and height r— 
are integer-expressions, specifying the number of pixels along the appropriate dimension of P ° 
the screen. The maximum size allowed is 4k pixels in either direction. 


To define the width and height of the virtual screen in absolute terms, dimensions should be 
SIZE width [ FIXED ]. height [ FIXED ]. width and height are (positive, non-zero) numeric- 
expressions, and in this form of the command they specify the width and height of the virtual 
screen in metres - not the actual size, but a nominal size based on how fonts appear on the 
screen. When a 72-point (ie. one inch) character is displayed on the screen, it does not 
necessarily appear one inch high as measured with a ruler against the screen - instead it 
appears as a representation of a one inch character. It is the height of this representation 
which is used to determine the screen height set by the SCREEN command. 



For example, if height were specified as 0.5 then (assuming 39 inches to the metre) the height 
of the virtual screen would be 19.5 times the height (in pixels) of a 72-point character. This is 
not necessarily 0.5 metres unless 72-point characters really do appear one inch high on the 
screen, width is determined similarly. 
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If the word FIXED follows the specification of the size, the dimension of the window is 
constrained to be the same as that dimension of the graphics screen. 

There are four possible options; they can be used in any order or combination, and they are all 
optional. They may be separated with commas, but this is not essential. 

UNIT w . h (where tv and h are integer-expressions) specifies the number of pixels by which 
the width and height of the window size will be allowed to change. If omitted, this defaults to 
one pixel. 

INFORMATION is followed by ON or OFF (or, equivalently, any Boolean expression). ON (or a 
non-zero value, or a true condition) specifies that the window will appear with an information 
line below the title bar. OFF (or 0, or a false condition) specifies that there is to be no 
information line. 

MINIMUM w . hand MAXIMUM tv, h (where wand hare integer-expressions) specify a minimum 
and maximum width and height for the window, in pixels. 

The SCREEN command clears the graphics screen (and window) and resets the screen 
attributes (size of user coordinates, position of user origin etc.) as described in Chapter 12. 
Details of the steps that are used to reset them are given in Section 12.1 'Setting up the 
coordinate system'. As far as possible, the window's current size and position are left 
unchanged. If the window is open, it is made the top window. 

If you need to reset all the windows (o their initial state (that is, the state they appear in when 
you load BASIC 2 Plus) the command to use is CLEAR RESET. 

If you use CLEAR RESET in the Dialogue window, it clears all the variables as well as 
resetting the screen. 


........ ... ......... ............................................. .......... . ............... ..... •'>' > 

Use CLEAR RESET sets all windows to their initial state, and, in Direct Mode, discards 






all variables. 

•' 11 gpi n | >||i! 

Syntax CLEAR RESET 
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9.2 Getting information about a virtual screen 

A number of BASIC 2 Plus functions return information about the virtual screen. They can be 
used to determine: 

• the size of the virtual screen 

• the cursor position 

• the colour of the screen at a particular point 

• the size represented by user coordinates 

9.2.1 The size of a virtual screen 

To determine the overall size of the virtual screen in user coordinates: 

width - XVI RTUAL/( ^stream-number)] 
height - YVIRTUAL/’( Iistream-number)] 

9.2.2 The cursor position 

The current position of the cursor on a particular screen can be determined at any time either 
in text coordinates (columns and lines) or, on a graphics screen, in user coordinates. 

The functions to use are as follows: 

In text coordinates: horizontal-position - POS [{# stream-number)] 

vertical-position - VP OS [(ft stream-number)] 

In user coordinates: horizontal-position - XP0S[( if stream-number)] 

vertical-position - YPOS/t Iistream-number)] 

9.2.3 The colour of a pixel 

To read the colour of a point being displayed in a graphics window, use the function TEST: 
result - TE ST ( [iistream-number,Jx;y) 

result is -1 if the specified point is not being displayed, otherwise it is the colour code for that 
point, in the range 0 - 15. 

TEST may not be available on your computer as it depends on the version of the underlying 
software that you are using. 
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XVIRTUAL & YVIRTUAL 

Use XVI RTUAl and YVIRTUAL are functions which return the size of a graphics virtual 
screen, or other graphics device, in user coordinates. 

Syntax XVI RTUAL/( [#]stream-number) ] 

Y VIRTU A L/( (^stream-number) ] 

Description XVI RTUAL returns the width of the graphics virtual screen, YVI RTUAL returns the 
height. These values are in user coordinates. 


pos & VPOS 

Use These function return the current cursor position in characters and lines. 

Syntax P0S[( (ftjstream-number) J 
V P0S/( [it]stream-number ) ] 

Description POS returns the current character position. V POS returns the current line position 
in user coordinates. 

xpos & YPOS 

Use XPOS and Y POS are functions which return the current cursor position in user 
coordinates. 

Syntax X P0S/( (ft]stream-number) ] 

YPOS/Y [ifjstream-number)] 

Description XPOS returns the position in the x dimension, YPOS returns the position in the y. 
These values are in user coordinates. 


TEST 

Use TEST is a function which returns the colour of a point on a Graphics Screen. 
Syntax TEST {^stream-number, J point) 

Description If the given point is visible then TEST returns the colour-number for the colour of the 
corresponding screen pixel - this is an integer greater than or equal to zero. 
Otherwise, TEST returns -1. 

TEST may not be available on your computer as it depends on the version of the 
underlying software that you are using. 
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9.2.4 The size of user coordinates 

You can also out how distorted a display the user coordinates give and the relationship 
between user coordinates and pixels, using the functions YASPECT. XPIXEL and YPIXEL. 
YASPECT gives (user coordinate height)/(user coordinate width). 

result - YASPECT [(.^stream-number)] 

If the display is symmetrical, result will be 1. 

XPIXEL and YPIXEL give the number of user coordinates per pixel in the appropriate 
dimension. 

pixel-width - X PIX E L /(# stream-number) ] 
pixel-height - YPIXEL/( ^stream-number)] 

Warning: When using these functions, you should note the warning in the next section. 


9.3 Getting information about the display 

The functions in the previous section give information about the virtual screen and user 
coordinates. They should be contrasted with the following functions, which give information 
about the real display - the actual screen connected to your computer. These functions return 
results in pixels, not user coordinates, because user coordinates only have meaning in the 
context of a particular window. 

Warning! The information returned by these BASIC 2 Plus functions can only be accurate if 
the information supplied from the screen is accurate. Unfortunately some screens simply lie 
about the information they supply, so you are recommended to test these functions carefully 
before relying on them. XMETRES and YMETRES are particularly likely to give wildly 
incorrect values. XMETRES and YMETRES are not in themselves very important, but many 
features make use of the ratio between them. If BASIC 2 Plus is misled about this, squares 
will appear oblong and circles will appear oval on the screen. 

To determine the display size in metres, use: 
width - XMETRES/( IIstream-number)] 
height - YMETRES/(// stream-number)J 

To determine its overall size in pixels, use: 
width - XDEVICE/( Ifstream-number)] 
height - YDEVICE/(// stream-number)J 
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YASPECT 

Use 

Y AS P ECT is a function which gives the aspect ratio of a user coordinate pixel. 

Syntax 

YA$PECT/( (jpstream-number) ] 

Description 

YASPECT returns the ratio of the height of a user coordinate to its width. 


If YASPECT is 1, a box n x n will be square (provided XMETRES and YMETRES 
returned by the device are correct). If YASPECT is greater than 1, the box will be 
taller than it is wide. If YASPECT is less than 1, the box will be wider than it is tall. 


XPIXEL & YPIXEL 

Use 

X PIX E l and Y PIX E L are functions which return the size of a device pixel, in 
user coordinates. 

Syntax 

X PIX E L/( Iti]stream-number) ] 

Y PIX E Lf( (jpstream-number)] 

Description 

XPIXEL returns the width of the device pixel, YPIXEL returns the height. 

These values are in user coordinates. 



XMETRES & YMETRES 

Use 

XMETRES and YMETRES are functions which return the size of a graphics device, 
in metres. 

Syntax 

XMETRES^ Upstream-number) ] 

YMETRESf( (]pstream-number) ] 

Description 

XMETRES returns the width of the graphics device, YMETRES returns the height. 
These values are in metres. 


XDEVICE & YDEVICE 

Use 

X D EVIC E and Y 0 EVIC E are functions which return the size of a graphics device 
in device pixels. 

Syntax 

XDEVICE^ [^stream-number) ] \ 

YDEV ICE/( (ipstream-number) ] 

Description 

XDEVICE returns the width of the graphics device, YDEVICE returns the height. 
These values are in device pixels. 
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To determine the size of the usable area in pixels, use 
width - XUSABLE/( if stream-number)] 
height- Y USAB LE/( iistream-number)] 

XUSABLE and XDEVICE wiU be the same, but YUSABLE will be less than YDEVICE, because of 
the presence of the GEM menu line. 
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Sequential Input 


Sequential input is available on three devices: sequential (ordinary text) files, 
communications ports, and windows. All three of these devices can be used for output, but 
this chapter is concerned only with input, and it therefore assumes that the device has been 
opened on a stream with an OPEN WINDOW or OPEN INPUT command, as described in 
Chapter 8. 

The principal statement used to input data from a sequential file, a communications port, or a 
window is INPUT. In its simplest form, the INPUT statement appears as 

INPUT [ llstream-number,] general-variable [. general-variable]... 

This assigns information from the input device to each of the general-variables in turn. If the 
input device is a window, information is taken from the keyboard and echoed to the screen as 
the user types. 

If the general-variable is numeric, INPUT will expect to find a (possibly signed) number on the 
stream. Spaces will be skipped up to the start of the number, which will then be assigned to 
the general-variable. The number may be a decimal, binary (&Xn) or hexadecimal (&n) 
constant. Numbers are terminated either by an end-of-line, the end of the file, or a comma. 
Underlines are permitted within numbers, and spaces are permitted anywhere within decimal 
numbers (even in the exponent part of scientific format numbers). The first 17 digits are 
taken; excess digits are regarded as placeholders only and treated as if they were zero. 

If nothing is found on the stream, general-variable takes the value 0. 

If the general-variable is a string type, INPUT will look for a string. Spaces will be skipped over 
until the first non-space character. If this is a double quote character ("), the text is read as a 
'quoted string' and all characters up to (but excluding) the next double quote or the end of the 
line are assigned to the string variable. 

If the first non-space character is not a double quote, all characters up to a comma or end of 
the line are assigned, dropping any trailing spaces. 

This means that both numbers and strings can normally be separated simply by commas. 
Quotes are only required round strings if you want to include commas or leading or trailing 
spaces. 
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INPUT 


Use 


INPUT inputs numeric or string values from sequential devices. 

Syntax INPUT $ stream], / / /AT ( col;line)][;][prompt]general-variable[, general-variable...](;] 
where the [,] after stream is required if none of AT, PROMPT or the first /;/ are present. 
col and line are integer-expressions giving the screen position at which to start. 

prompt is prompt-string prompt-separator 

where prompt-string is PROMPT string-expression or string-literal 
and prompt-separator is, or;. 

Description INPUT reads characters from the given stream and extracts values to be 
assigned to the given general-variables. The way this is done depends on the 
general-variables and on the device attached to the stream. 


For screen devices: If the AT ( column; line ) is present, the cursor is moved to the position given. If a 
prompt is present, that is output followed by a ? if the prompt-separator was ,. If no 
prompt is present the default prompt of ? is output. Characters are then read from 
the keyboard and reflected to the stream, until return is pressed. Before return is 
pressed backspace may be used to amend the input. When return is pressed the 
characters input are processed to extract values to be assigned to the given 
general-variables. This processing treats the input as items separated by commas. 
There must be exactly the same number of items as there are general-variable s. 
Each item may include leading and trailing spaces and tabs, which are ignored. 
For a numeric general-variable the remainder of the item must be a corrently formed 
signed number or may be null (which is treated as zero). For a string general- 
variable the remainder of the item may be "string”, which may contain commas, or 
otherwise may be any collection of characters not including comma. If for any 
reason the input is not acceptable an alert informs the user, who may then correct 
the input and press return again - if the input is still unacceptable this process is 
repeated. Finally, if neither/;/ is present a return is output. 


For other devices: Any AT ( column; line ) or prompt is ignored. The input is treated as items separated 
by commas or carriage returns. Each item may include leading and trailing 
spaces and tabs, which are ignored. For a numeric general-variable the remainder 
of the item must be a corrently formed signed number or may be null (which is 
treated as zero). For a string general-variable the remainder of the item may be 
"string”, which may contain commas, or otherwise may be any collection of 
characters not including comma. If for any reason the input is not acceptable an 
error is raised. 
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An alternative statement for taking information from a stream is LINE INPUT. This reads the 
whole of the line (ie. it reads all the characters up to the next carriage return) into a single 
string variable. It is otherwise identical to INPUT. 

To input a fixed-length string, use the INPUTS function. INPUTS returns a fixed-length 
string. It does not display the characters typed on the screen, and will accept any characters. 
Its argument string-length is a numeric-expression yielding the length of string required: 

I NPUTS ( l llstream-number . ] string-length ) 






”, 


riT 
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Use 

Syntax 

where 


LINE INPUT 

LINE INPUT inputs a complete line from sequential devices. 

LINE INPUT $stream( , ]] [AT ( column; line)][;][prompt] string-general-variable [;] 
the [.] following the stream-number is required if none of AT, PROMPT or the first [: ] 
are present. 

column and line are integer-expressions giving the screen position at which to start the 
prompt etc. 

prompt is prompt-string prompt-separator 

where prompt-string is P ROM PT string-expression or string-literal 
and prompt-separator is , or;. 

LINE INPUT reads a complete line of characters from the given stream and 
assigns it to the given general-variable. 

If the AT( column; line) is present, then the cursor is moved to the position given. If 
a prompt is present, then that is output followed by a ? if the prompt-separator was .. 

If no prompt is present then the default prompt of ? is output. Characters are then 
read from the Keyboard and reflected to the stream, until return is pressed. 

Before return is pressed the user may use backspace to amend the input. When 
return is pressed the characters read are assigned to the given string-general- 
variable. Finally, if neither [; ] is present a return is output. 

For other devices: Any AT( column; line) or prompt is ignored. Characters are are read from the stream 
up to the next return and assigned to the given string-general-variable. 


Description 


For screen devices: 


- 2^*9 
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INPUTS 

Use INPUT* is a function which returns a string containing a given number of 
characters read from a given stream. 

Syntax INPUT % (^stream-number, count) 
or INPUTS (count. Upstream-number) 
where count is an integer-expression, giving a value in the range 1 ..4096. 

Description INPUTS reads count characters from the given stream, and returns them as a 

string. If the stream is connected to a screen device, then input is taken from the 
keyboard but nothing is reflected to the stream. 

INPUTS reads "raw" characters and is generally useful only where the exact form 
of the input is known. 


The string read in docs not need any terminating character. If it is input from the keyboard, 
the user should not type E] to end the string (indeed, it would be included in the reply, if 
typed!). Keys like i«-on will simply type their character in the reply. Users will have to be 
warned about this. 


10.1 Information from files and communications links 

When the statements described above are executed, information is read from the stream in 
stricdy sequential order (whence 'sequential file'): the first general-variable in the INPUT 
ttstream instruction will be assigned from the first value on the stream, the second general- 
variable from the second value, and so on. It is not possible to read backwards or re-read an 
item. However, if a file is open on more than one stream, each stream will handle the file 
sequentially, regardless of the progress of the other stream. 

For example, if the file NUMBERS.TXT contains the following data: 1, 2. 3. Then the 
program 

OPEN #5 INPUT "NUMBERS.TXT" 

OPEN #6 INPUT "NUMBERS.TXT" 

INPUT #5. flvel, ffve2 
INPUT #6. sixl, s1x2 
PRINT flvel; f1ve2: sfxl; s1x2 
CLOSE : END 






will produce 
12 12 
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The values read from a sequential file will not necessarily correspond with that written to it, 
unless care has been taken with the separators. For more information about this, see the 
section in Chapter 11 entitled 'Writing with reading in mind'. 


Reading past the End of File 



Attempting to read beyond the last data item in a file will generate an error. This can be 
avoided by knowing how many items are in the file, or by adopting a convention of writing a 
unique value as the last entry in a file, then testing each item read against this. For example, if 
the end marker were " 77.7. ", you could print the whole file using: 

DO 

INPUT #6. item! 

IF items <> "III" 

THEN PRINT itemS 
ELSE EXIT DO 
END IF 
LOOP 

However, a more elegant method is to use the function EOF. E0F(# stream-number) returns 0 
('false') while there are more items to be read from the Hie, -1 ('true') when the last item has 
been read. For example, to print all the entries in a file: 

DO UNTIL E0F(#6) 

LINE INPUT #6. itemS 
PRINT itemS 
LOOP 
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10.2 Information from the keyboard 

When an INPUT statement is applied to a stream connected to a window, it takes data from the 
keyboard, which is echoed on the screen as the user types. It expects the information in the 
form described above: if it is reading into a numeric-general-variable, it expects a number, if it 
is reading into a string-general-variable, it expects a string. The only difference in the format is 
that the data items must be separated with commas (not end-of-linc or end-of-filc): only the 
final item is terminated with a carriage return. 

If data is entered in an incorrect form (the wrong type of data, for example, or the wrong 
number of data items) an alert will be displayed. When the user has clicks on RETRY, the alert 
will clear, and the user will be able to use the r*o5l key to edit and retype the information, 
before pressing GEJ to enter it (Of course, any mistakes the user notices before GD is 
pressed can be corrected using the key.) 

The other difference when reading data from a window is that the user can be prompted to 
type in the data: 

INPUT [ itstream-number ] (prompt separator ] general-variable[.general-variable...] 

prompt must be a string constant or the keyword PROMPT followed by a string-expression. If the 
separator is a semicolon, the prompt will be followed by a question mark when printed. If it is 
a comma, no question mark will be added. 

If the stream referenced is connected to an input device other than a window, any prompt will 
be discarded. 

When the user presses GO, the text cursor usually advances to the start of the next line. To 
suppress this, so that the cursor remains at the end of the text the user types, put a semicolon 
at the end of the statement. For example: 

INPUT "Point co-ordinates, x and y":pointx,pointy: 


Single key input 

If you want the user to make a choice by pressing particular keys on the keyboard, you need 
to use either the INKEYS or the INKEY function. 

IN KEYS either returns a single character corresponding to the key being pressed, or if no key 
is being pressed, it returns a null string. Note that INKEYS docs not display the character 
typed, nor does it wait for keys to be pressed. 
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INKEY 

Use INKEY is a function which returns a numeric value corresponding to a key press. 
Syntax INKEY 

Description INKEY looks to see if the user has typed anything. If not, then INKEY returns -1. 

if the user has typed anything then I NKEY returns a value in the range 0..511 
corresponding to the key pressed. The values 0..255 correspond to character 
keys, and are the ASC of the character. The values 256..511 correspond to non¬ 
character keys, see Appendix I for a list of these. 

INKEY$ 

Use I NKEY $ is a function which returns a string value corresponding to a key press. 
Syntax INKEY$ 

Description I NKEY$ looks to see if the user has typed anything. If not, then INKEY $ returns a 
null string. If the user has typed anything then what INKEYS returns depends on 
which key it was, and on the current OPTION I NKEY $ string. If the key pressed 
produced a character, then INKEYS returns that as a single character string. If a 
non-character key was pressed - one for which INKEY would return a value in 
256..511 - then INKEY$ either returns a single character string or ignores the 
key. INKEYS may be thought of as if it were a user FUNCTION : 

FUNCTION inkeyS 

SHARED option_inkey$ * current OPTION INKEYS string 
DO 

ch = INKEY 
IF ch > 255 THEN 

ch$ = option_inkeyS{ch - 255} 

IF (chSO’"') AND (chSOCHRS(O)) THEN ch - asc(chS) 

END IF 

LOOP UNTIL ch < 256 

IF ch < 0 THEN inkeyS - chr$(ch) ELSE inkeyS - END IF 
END FUNCTION 

What this means is that the OPTION I NKEYS string may be used to provide 
character values for I NKEYS to return for the non-character keys. 
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INKEYS is usually used within a loop. For example: 

00 

a$-INKEY$ 

LOOP UNTIL aSO"" 

PRINT aS; 

INKEY is veiy similar to INKEY $, but returns a numeric result: -1 if no key has been pressed, 
otherwise the character value. (BASIC 2 Plus assumes an extended character set with 
character values 0-511.) 



Not all keys correspond to a character, and a special mechanism is used to return a Tcey value' 
in cases where it does not In this case, INKEY returns 256 + the key value (i.e. for a key value 
n, INKEY returns m-256). 

If a key of value n does not correspond to a character, INKEYS returns the /7th character of a 
special character string (the IN KEYS-string). If n is greater than the length of the I NKEY $- 
string, or the appropriate character in the IN KEYS-string has internal code zero, then INKEY S 
will return the null string. 

The INKEYS-string is initially set to 256 characters, all with internal code zero. OPTION 
INKEYS can be used to set the INKEYS-string and has the syntax: 

OPTION INKEYS string-expression 
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Sequential Output 


This chapter describes the facilities provided for sequential output - output of character 
codes from 0 to 255 (byte values), including the text characters from GEM'S character set 
(described in Appendix I). It gives the BASIC 2 Plus statements used to send characters to 
devices which accept sequential output: printers, communications ports, text and graphics 
windows, and sequential files (ordinary text files). Graphics windows also accept graphics 
output, but this is not described until the next chapter. 

As explained in Chapter 8, before any output device can be used, it must be opened on a 
stream, either explicitly by the user’s program, or (in the case of Results-1, Results-2 and the 
printer) automatically by BASIC 2 Plus. The output command then directs data to the stream, 
not to the output device directly. 

This chapter assumes, then, that the device accepting output has been opened on a stream. It 
begins with a description of the PRINT statement, which is used for all sequential output 
There is a description of how P RI NT is used to direct output to a general stream, and this is 
followed by a discussion of the various sequential output devices and their peculiarities. 


11.1 The common factor - the PRINT command 

Text is output using a P RINT statement. This always starts with the keyword PRINT, followed 
by a combination of items to output Cprint items'), functions to control the output, ('print 
functions'), and templates to control the formatting. PRINT statements can also contain 
separators (semicolons and commas). Print items, functions, templates, and separators can 
occur in any order provided that no print item direedy follows another (Hint item or a 
template. 

Print items are simply string- or numeric-expressions. 

Print functions are special functions which can be incorporated into a PRINT statement to 
control the position or the form of the information 

Templates are string expressions which follow the word USING in aPRINT statement They 
define the format used for numbers and strings which follow. 

For example, a PRINT statement might be 

PRINT number. zone(5), USING "$$***", cash, discount 

Here number, cash, and discount are print items, zone(5) is a print function and 
"$$***" is a template. 
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When PRINT is used to output a numeric expression, the expression is automatically 
converted to text: there is no need use BASIC 2 Plus's functions to convert numbers to strings 
unless the format used by PRINT is unsuitable. 

Unless the last character in a PRINT instruction is a semicolon or comma, a new line 
character will be output after the PRI NT instruction has been executed. A final semicolon or 
comma prevents this. A useful consequence is that the statement PRINT, on its own, simply 
begins a new line. 

The chief means of formatting the output is with a USING-template. Text and numbers can 
have their output format rigidly specified in a variety of ways by including a US I NG-template 
in the PRINT statement. 

If a print item has the keyword USING anywhere before it in its print statement it is output 
formatted. If not, its format follows the rules for unformatted output 


The next two sections of this chapter now explain the conventions and commands used in 
unformatted and formatted output. 



PRINT 

Use 

PRINT outputs numbers and strings. 

Syntax 

PRINT [ft stream-number] J] [print-item...] 

where 

the [.] following the stream-number is required if the first print-item is an expression. 


each print-item may be : expression 
or separator 

or print-command- see Print Commands box 

or print-function - see Print Functions box 

or USING string-expression; 

provided that no expression immediately follows another. 


separator is , or; 

Description 

PRINT processes the print-items in turn and sends the result to the given stream (or 
the current default, if none given). The result of each item depends on the item 
and on whether the output is "unformatted" or "formatted". Output is 
"unformatted" unless a USING item has been processed, when it is "formatted". 
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PRINT COMMANDS 


Use These may be used in PRINT or LPRINT statements. 


Syntax AT ( column; line) 

T A B ( integer-expression) 

ADJUST (integer-expression) 

Description These may be used in PRINT and LPRINT statements. They move the print 
position: 

AT - moves the cursor to the given position. 

TAB - moves forward to the given column position. If is already past that 

column, then performs a carriage return first. 

ADJUST - sets a the given point size and moves the cursor down by the 

difference between the new point size and the default point size. 
The point size setting is forgotten at the end of the statement. 

PRINT FUNCTIONS 

Use These may be used in PRINT or LPRINT statements. 

Syntax Z 0 N E ( integer-expression) 

MARGIN( integer-expression) 

E F F E C T S ( integer-expression integer-expression ) 

MODE ( integer-expression) 

C 0 LOU R ( integer-expression) 

C 0 LO R ( integer-expression) 

F 0 N T ( integer-expression) 

P 01N T S ( integer-expression) 

ANG LE ( integer-expression) 

Description These functions may be used in PRINT and LPRINT statements. They take 
effect immediately, but the effect is forgotten at the end of the statement. The 
attributes set are the same as the equivalents in the SET statement. 


11 
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11.1.1 Unformatted Output 

Unformatted strings are completely straightforward: the string is output exactly as given. 

Unformatted numbers are output as decimal numbers rounded to 9 significant digits, by 
default, though this depends on the size of the 'print zone' (see below). The maximum is IS 
significant digits; unformatted numbers are never output with more than 15 significant digits. 

Unformatted numbers are always output with a trailing space and a leading space or minus 
sign, and they never occupy more space than the print zone size - 18 characters, by default. 
If there are no digits before the decimal point, a zero will be printed: 

0.31831 

If necessary the number will be printed in scaled (exponential) format, ie. as a decimal 
number followed by an exponential part: E ±nnn. This indicates that the decimal number is to 
be multiplied by a scaling factor of lO*"". 


Positioning in Unformatted Output 

Items may be separated by semicolons, in which case they are printed immediately after the 
previous item. If one or more commas are used as separators, each comma moves the cursor 
to the start of the next 'print zone'. Print zones are positions every n characters across the 
screen, and n is initially set to 18, though this can be changed using the command SET ZONE. 

SET ZONE cells 
where cells is a numeric-expression. 

In the case of output to the screen, a new line will be started if no complete zone remains on 
the screen. A new line will also be started if the item will not fit on the current line, and the 
cursor is not already at the start of a line. 


Setting the zone size and then separating print items with commas therefore provides an easy 
way of tabulating items of similar lengths. 


SET ZONE changes the size of print zones permanently; the new values are kept even after 
the program terminates. Print zones can also be changed temporarily by using the print 
function ZONE (cells) where cells is an integer-expression. This has the same effect as SET 
ZONE, but only on the subsequent output in the PRINT instruction in which it is used. 


ZONE 

Use ZONE sets the print zone size for the Dialogue Screen. 
Syntax ZONE zone-size 


__ 


_ 
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You can also position text within a PRI NT instruction by preceding it with the print function 
TAB (x). This positions the next print item to begin at column x on the current line, or at 
column x on a new line if more than x characters have already been output. 



TAB without an argument is interpreted as a tab character (Control-I) moving to the next tab 
stop. (Note that the tab positions are not necessarily the same as print zones.) 

Problems with Escape Sequences 



Escape sequences are described in Section 11.1.3, but one problem they have is directly 
connected with tabs and print zones, and so it seems appropriate to discuss this here. 




When outputting to a device other than the screen, BASIC 2 Plus calculates print positions 
specified by tabs and print zones by maintaining a 'logical print position' on each line of the 
output Each character printed increments the logical position by 1 unless it is a control 
character with internal value #00...# IF; these count as having zero width. 

Escape sequences start with a control character but may contain 'normal' characters. The 
presence of these characters doesn't affect the actual position, but the logical position is 
incremented by 1 for each 'normal' character. So the logical position may not correspond to 
the actual position after a control sequence has been output. This can cause print zones and 
tabs to give incorrect results if control sequences are used. 



11.1.2 Formatted Output 



—ET». 



Formatted output is dictated by a USING-template in the PRINT instruction. The syntax for 
this is: 

PRINT [items] US IUG format-template separator using-list 
where separator is : or ,. 

The format-template is a string-expression that specifies how to format the items in the 
following using-list when they are displayed, items before the USING keyword arc output 
unformatted. 




using-list consists of items to print separated by commas or semicolons - commas and 
semicolons are not distinguished in formatted output: their purpose is only to separate, and 
they have no bearing on the output. 

When using formatted output (in contrast to unformatted described in the last section) items 
are not checked to sec if they will fit onto the line, but simply printed consecutively, as 
dictated by the format-template . Print zones have no effect, and inserting new lines in 
appropriate places is the responsibility of the programmer, not BASIC 2 Plus. 
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format-template is a string-expression consisting of one or more templates, optionally separated 
by non-template characters. Each template indicates how to format a single string or numeric 
item in using-list, as follows. The first item in the list is formatted according to the first 
template, the second item according to the second template, and so on. If there are more items 
in using-list than templates, the format-template will be used again - with the next item in the 
list being formatted according to the first template, the one after that according to the second 
template, and so on. 

The forms these templates can take are described below. If the template expects an item of the 
wrong type, ie. a string instead of a number or vice versa, an error will result 

Any characters included in format-template that arc not template characters will themselves be 
output at the corresponding position in the formatted output, between the formatted print 
items. For example, notice how the spaces and equals sign are printed in the high-score table 
example in the next section. 

To explicitly print a character which is a template character, precede it with an underscore. 
The underscore is not printed. 


Formatting strings 

Templates to format strings must be one of the following: 

1 print just the first character of the string 

\n-spaces\ print the first n+2 characters of the string 
& print the whole string 

For example, to print a table of names and scores: 

DATA Superman. 100, Ant. 1, Attila the Hun. 99 
FOR count - 1 TO 3 
READ person), score 

PRINT "Score for ";USING "\ \ - M ;person$; 

PRINT score 
NEXT count 

This would print: 

Score for Superman = 100 
Score for Ant - 1 
Score for Attila th - 99 

(In the last line, "Attila the Hun" has been truncated by the 9-charactcr template) 

If the string being output is shorter than the template specified using "\space$\\ it will be 
padded with spaces, on the right. 
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Formatting numbers 

Numeric items are formatted with a numeric template. This is far more complex than a string 
template; it consists of a combination of the following characters: 

#.+-*$ A \ 

As long as the template is large enough, the formatted number will be the same length as the 
template, and with the decimal point in the same place; this greatly simplifies tasks like 
printing tables. 

Each # in the template specifies a digit position. If there is no . in the template, only the 
integer part of the number will be output, with no decimal point. If there is a . in the template, 
a decimal point will be output at that position. The number is rounded to the number of places 
after the point. 

A . anywhere to the left of the . (if present) specifies that digits to the left of the decimal 
point should be grouped into threes, separated by commas. So that the formatted number is 
the same length as the template it is good style to put in commas after every third #, as in the 
example. If you prefer, another character can be output as the thousands separator see 
'National variants', below. 

Similarly, a \ to the right of the decimal point and before the last # specifies that the digits to 
the right of the point should be grouped into fives, separated by spaces. 

Thus, to print a number as 4 digits with no decimal point or decimal places, the template 
would be: 

mm" 

For example: 

PRINT USING "####":12.345 
would print: 

12 

while 

PRINT USING "####";1234.7 
would print: 

1235 
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To produce 9 digits, grouped into threes, with 2 decimal places: 

"m.m.m.H” 

For example: 

PRINT USING "###.###.###.##”:12345.678987654 
would print 

12,345.68 

and 

PRINT USING "###.##]P.###.#####\#####\##### N s12345.678987654 
displays as 

12,345.67898 76540 00000 

If the template is larger than the number it has to accommodate, leading places will usually be 
padded with spaces (but see below), and trailing places after the decimal point will be filled 
with zeros. • 

If it is too small, the output depends on whether there are too few # signs before or after the 
point. If there are too few after the point, the number is rounded to make it fit. If there are too 
few before the point, the number obviously cannot be rounded or truncated without grossly 
distorting its value. Instead, more digits are output than the template specifies, up to a 
maximum of fifteen places before the point. If even more digits are required (and are not 
allowed for in the template) the number will be output in scaled format. 

Thus, for example, a template of # will print any size number up to fifteen digits long, 
rounded to the nearest integer, using the least amount of space. 

A positive number is normally printed without a sign, while a negative number will lie 
printed with a minus sign immediately before the first digit. (The minus sign occupies one of 
the specified digit positions.) 

To control the placing and use of signs, put a + or - at the start or end of the template. A - 
specifies the position for a space (if positive) or minus sign (if negative). A + specifies the 
position for a plus sign (if positive), or minus sign (if negative). 

To specify that instead of leading spaces, leading asterisks should be output when the number 
being printed is smaller than the template, place ** at the start of the template (but after any 
leading sign). This also automatically specifies the first two digit positions at the beginning 
of the template: for example "**////////" specifies 6 digits with leading asterisks where 
appropriate. This form is often used when printing amounts of money (for example, on 
cheques). 
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To specify that the printed number should start with a currency symbol, put $$ at the start of 
the template (but after any leading sign). This automatically specifies the first digit position 
at the beginning of the template. Normally, the currency symbol that will be printed is the one 
that corresponds to the nationality of the operating system that you are using but you can 
change the currency symbol (see National variants, below). If you change the currency 
symbol, you should still use $s in the template, but if the currency symbol is more than one 
character, you should use an extra $ in the template for each additional character. For 
example, if the currency symbol is FFr, use $$$$ in the template. 

To specify leading asterisks and a currency symbol as well, place **$ at the start of the 
template (but after any leading sign) - this also specifies the first two digit positions. Again, 
use extra S symbols in the template if the currency symbol is more than one character. 

So to print a number with leading asterisks, 6 digits and a trailing minus sign, use: 
"**####-" 

To specify 9 digits in groups of three, 3 decimal places, leading asterisks, $ and either a + or a 
- sign: 

"+*$$#.###.###.###" 

Finally, you can specify that the number be printed using an exponent, by adding AAAA to the 
end of the template (before any trailing sign), or AAA *, which outputs numbers with an 
exponent that is a multiple of 3 (engineering form). The exponent will consist of two digits, 
unless the number is so big that three are required. If you wish to force the exponent to have 
three digits, include an extra A thus: AA AAA or aaaa * respectively. For example: 

PRINT USING "###.### AAA *":1.23E43 
would produce: 

12.300E+42 

As described previously, a format template can consists of templates for more than one item, 
so to tabulate the scores in the previous example properly, you could use: 

DATA Superman. 100, Ant. 1, Attila the Hun, 99 
FOR count = 1 TO 3 
READ person$, score 

PRINT "Score for ";USING "\ \ - W'spersonS; score 
NEXT count 

This would print: 

Score for Superman - 100 

Score for Ant = 1 

Score for Attila th = 99 
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National variants 


BASIC 2 Plus caters for national differences in the character used as the decimal point 
character, the thousands separator, and the currency symbol. 

Decimal fractions normally use a full stop or comma as the decimal point character 
(depending on which country's version of DOS your computer uses). To change to a different 
character, use: 

OPTION DECIMAL point, separator 

point is a string expression, the first character of which will be used as a decimal point. 
separator is a string expression, the first character or which will be used as the thousands 
separator when numbers are output with a USING template. This has no effect on the formal 
expected by the INPUT command. There is no way of changing the decimal space separator. 

The default currency symbol depends on the country code of your computer's operating 
system; it can be changed using: 

OPTION CURRENCY* character-string 

character-string is a string expression, which will be used as the currency symbol instead of 
dollar (*) signs, when using PRINT USING and the function DEC*. (Note: the number of 
characters of this string that will be used depends on the number of $s in the format template 
up to a maximum of 15. For details, see 'Formatting numbers' above.) 


CURRENCY* 

Use CURRENCY $ is a function which returns the current "currency string". 

Syntax CURRENCY* 

Descri pti on CURRENCY* returns a string containing the current "currency string" - the string 
used by PRINT if **-type templates are used. 















11.1.3 Controlling the output device with codes 

Print functions and format templates aren't the only method for controlling how output is 
presented. Output devices can be controlled by sending them special sequences of 8-bit 
codes, embedded among the characters to be output. These control sequences are typically 
either single characters with internal values in the range 0...31 or short groups of two or three 
characters, the first of which is the 'Escape' character (internal value 27; also known as ESC). 
The former are called 'control characters'; the latter are 'escape sequences'. They are 
recognised by the output device and rather than being output they are interpreted and acted 
upon accordingly. 

The actual facilities and the codes required depend on the output device. Control sequences 
to use with your printer will be given in its user guide. In the case of the screen, the codes are 
part of BASIC 2 Plus, and details are given in Appendix II. 

(BASIC 2 Plus's print functions and screen handling commands give you just as much 
control over the screen as do control sequences. However, control sequences are more 
versatile (although they do tend to make PRI NT statements less intelligible), since they can be 
stored along with text in suing variables, and manipulated with BASIC 2 Plus's suing 
handling features.) 

The best way of showing how to use control codes is through an example. Suppose, for 
instance, that you were sending data to a text window, and you wanted to clear the screen. 
Looking at the appendix on Screen control codes, you will see that the control sequence to do 
this is ESC E. The characters of this sequence can appear either as an individual print item, or 
embedded within other string print items. Either way, ESC E must be sent to the output 
stream in a PRINT statement. 

If a code is associated with a printable character, you can express it as ''character*'; so to 
specify E, you can put "E" 

Codes with special names don't represent printable characters and you have to express them 
using C H R$ ( value ) where value is the code's internal value. E SC has the internal value 27 and 
so to specify ESC, you put CHR* (27). So to clear the screen, the statement to enter is: 

PRINT [Itstream] CHR$(27):"E" 

Of course, you can clear the screen more easily with the BASIC 2 Plus statement CIS. 
Nevertheless, this example serves to explain the principle of how escape sequences can be 
embedded in print items to control an output device. Other commands to control other 
devices can only be expressed as embedded control sequences. 
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11.2 Text output on Windows 

When you output text on the screen, you have options which are not available on devices 
such as communications ports or sequential files. You can style the text in various ways, for 
example, - making it bold or light or italic or underlined. On a colour screen, you can choose 
which colour it is printed in. You can also position your text anywhere you want in the 
window and delete text that you no longer require. 

This section describes the facilities provided specifically for handling text output in BASIC 2 
Plus's windows. Except where specifically noted all statements made about text screens in 
this section apply equally to graphics screens and other graphics devices. 

The cursor indicates the current position. Each time a character is displayed, it is placed at the 
current position of the cursor. TTie cursor then advances to the next character cell across the 
virtual screen. 

When the character is displayed in the screen's rightmost column (which may or may not be 
visible in the window), the cursor will normally move to the start of the next line. This 
automatic wrapping can be prevented by using the command: 

SET [itstream] WRAP OFF 

The cursor will now move to the start of the next line only when a carriage return and line 
feed are output to the screen. Any excess characters will be oveiprinted in the last column. 

To restore normal wrapping, use the command: 

SET [itstream] WRAP ON 

When text is output unformatted, a new line is begun whenever a print item will not fit on the 
current line (see Section 11.1.1). This is not affected by changing the WRAP mode. 

11.2.1 Styles of text 

You can vary both the style (thick, light, italic, etc.) and colour used to display text in the 
window. This is done by using print functions, by using the escape sequences that correspond 
to them, or by using the SET function. 



To change the colour of subsequent items in a print statement, include the print function 
C0L0UR( colour-number). For example: 

PRINT "You are ";C0L0UR(2);ABS(balance);C0L0UR(1);"overdrawn" 


(The colours available depend on your computer. Refer to the guides supplied with it for 
details.) 
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To change the text style, include the print function EFFECTS* effects-1[,effects-2]). in the 
PRINT statement Both effects-1 and effects-2 are numeric expressions, the values of which 
specify a particular combination of print effects, effects-1 specifies the effects to be turned on; 
effects-2 specifies the effects to be turned off. 

The interpretation of effects depends on which bits are set in its binary representation. Bits 0 
to 6 have the following significance: 


Bit Binary representation Effect 

0 &X0000000 thick 

1 &X0000010 light 

2 &X0000100 italic 

3 &X0001000 underlined 

6 &X1000000 reversed 


Note that text can be displayed using any combination of these effects, although certain 
combinations will not be very attractive or legible! 

You will probably find that the easiest way to specify effects is in binary notation. For 
example, you could define constants with the statement: 

CONST italic = 4X0000100 . reversed = 4X1000000 

and then specify italic reversed text with the constant i tal i c + reversed.which will give 
you a combined effects of &X1000100. 

Text style can also be changed by printing escape sequences, as listed in Appendix II. 

Permanently Changing the Text Styling 



To change the colour or print effects used in all subsequent print instructions, use the 
command SET, followed by the appropriate print function(s), which this time don't have 
brackets around their parameters. For example, to set the colour to 1 and effects to light italic. 

SET [ffstream] COLOUR 1 EFFECTS 4X110 

Note the difference between print functions in PRINT commands, which change the style 
temporarily (for the rest of the PRINT command) and print functions in SET commands, 
which change the style used as a default in all subsequent PRINT commands. 

To restore the text style to its initial state and clear the screen, use: 

CLS [ffstream] RESET 

The text style is automatically reset to its initial state if the screen or its window is redefined 
using a SCREEN TEXT or a SCREEN GRAPHICS command (see Chapter 14 The Display 1 ). 
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11.2.2 Positioning text 

There are various statements, print functions, and control sequences which control where the 
cursor is positioned in the window, and hence where the next character is displayed. None of 
these will move the cursor outside the area of the screen. Instead, the cursor will be moved as 
far as possible in the requested direction, and will be positioned in an appropriate place at the 
edge of the window. 

To move the cursor to a new position directly, use the command: 

LOCATE [llstream] column;row 

where column and row are numeric-expresions. This moves the cursor to the character cell with 
coordinates column\row. 

You may choose to omit either column or row in which case the corresponding value in the 
current cursor position will be used instead. If you want to specify the column, then you just 
need to specify the relevant column number, but if you want to specify the row, you need to 
include the semicolon. 

You can also position output by using the print function AT( columrrjow ) which has the same 
effect as LOCATE, except AT is a print function, and so is included inside a PRI NT statement, 
whereas LOCATE is a statement in its own right.. 

To move the cursor vertically on the screen, you can use the statement TEXT FEED n , which 
moves the cursor down the screen n lines without moving it horizontally. If n is negative, the 
cursor moves up the screen. For example: 

TEXT ///streamy FEED -5 

will move the cursor up the screen five lines. TEXT FEED will not move the cursor off the 
virtual screen. 

Positioning can also be controlled by printing control codes and escape sequences. For 
details, sec Appendix II. 

11.2.3 Clearing a text screen 

You can clear either the whole or part of a screen, removing previous output. 

To clear the whole screen, use either CLS which clears the screen and moves the cursor to 
the top left-hand comer, or CLS RESET which also restores the text style to its initial state. 

A number of other screen-clearing facilities arc also provided. These are only available on 
text screens; they are not available on graphics screens and other graphics devices. 
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LOCATE 

Use 

LOCATE moves to a given character and line position. 

Syntax 

LOCATE [ihtream-number.J column;line 

Description 

The cursor is moved to the given column and line position. 


CLS 

Use 

C LS clears a virtual screen. 

Syntax 

CLS /reset; 

or 

CLS fflstream-number [[.) RESET/ 

Description 

CLS clears the virtual screen attached to the given stream (or the default stream, 
if none given). The qualifier RESET resets all SET parameters to their standard 
states - see page 218. 


General screen clearing facilities are provided by: 

TEXT CLEAR quantity 
where quantity is one of the following: 

EOL clear from the cursor to the end of the line inclusive 

BO L clear from the beginning of the line to the cursor inclusive 

LINE clear the whole line containing the cursor 
EOS clear from the cursor to the end of the screen inclusive 

BOS clear from the beginning of the screen to the cursor inclusive 

SCREEN clear the entire screen (equivalent to CLS) 

To delete an area of the screen, ie. to remove it and pull in the surrounding text to replace it, 
use: 

TEXT DELETE to delete the character at the cursor 

TEXT DELETE LINE to delete the line containing the cursor 

To insert a line ie. to move all text below and including the cursor line down a line and leave 
a blank line, use: 

TEXT INSERT LINE 

As an alternative to using the TEXT and CLS commands, you can use the escape sequences 
listed in Appendix 11. 
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11.2.4 Wrapping and Indenting text 

Another aspect of the text that can be changed is the left-hand margin BASIC 2 Plus uses 
when wrapping text from one line to the next 

When the text cursor moves to the next line as a result of wrapping at the righlhand edge of 
the screen, it will normally move to the first character cell of that line. To change this, use the 
print function MARGIN: 

PRINT [^stream,] MARGIN! position): items 

position is an integer expression, specifying the column position, as the number of character 
cells. 


11.3. Special features of printer output 

Output to a printer is similar to output to the screen, but is rather more limited. In particular, 
many printers will not print the accented characters, Greek symbols or print effects as they 
are displayed on the screen. 

However, if your printer is TBM-compatible', it should print characters with codes other than 
176 - 207 as they are displayed in the standard text font. 

The standard printer (PRN) is automatically opened when any output is directed to stream 0. 
So text can be printed on this printer simply by specifying stream #0 in the P RIN T command 
as follows: 

PRINT #0 .... 

Of the print functions, only TAB(jc) and ZONE(/i) can be used. Other print functions (eg. 
those valid when outputting text to a text screen) will simply be ignored. The TAB character 
will be output as Control-I, rather than expanding it to a number of spaces. 

Output can also be sent to the standard printer by using the command LPRINT. LPRINT is 
identical to PRINT except that it always sends data to stream #0 rather than taking the stream 
number as a parameter. 



You may control the position of output on a page by using the printer's own control codes. 
BASIC 2 Plus docs not interpret or trap control codes and escape sequences in output routed 
to a printer, so to control the printer, simply include the appropriate codes in print statements. 
Refer to the printer user guide for details of the escape sequences and control codes it obeys. 







Use LP RI NT is just like print, except that the output is always to stream 0. 
Syntax LPRI NT [print-item...] 

Description See P R I NT, remembering that the output is to stream 0. 



LPRI NT 






11.4 Special features of file output 


Outputting information to a disc file provides a way of preserving information so that it can 
be used later either within the same program or by other programs. 

BASIC 2 Plus handles three different types of disc file: sequential files, random files and 
keyed files. This section only considers sequential files. 

When writing to a sequential file, print functions other than ZONE, and TAB are ignored. Tab 
Control codes are inserted as CH R$ (9); they are not expanded to spaces. 


Writing with reading in mind 


One purpose of creating a file with PRINT Ustream-number is to put information in it that can 
be read back into similiar variables later, using INPUT (as described in Chapter 10). 

When you do this, you will usually want to read information back from a sequential file 
exactly as it was written. 

The simplest way to ensure this is to use a separate PRINT if stream instruction for each item 
when creating the file. This will place a carriage-return character after each item written in 
the file: this is a valid separator for strings and for numbers. You can then read the file using 
the same types of variable in the same order as were used to create the file. 
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For example, if the file was created using: 

OPEN #file OUTPUT "names" 

FOR entry - 1 TO 10 
PRINT #file,surname!(entry) 

PRINT #file.address!(entry) 

PRINT //f 11 e.telephone(entry) 

NEXT entry 

Then the information could be read back using: 

OPEN #file INPUT "names" 

FOR entry - 1 TO 10 

INPUT #fi1e.client$(entry),address$(entry).phone(entry) 

NEXT 

Note that, as shown here, you need not use the same names for the variables, just the same 
types. 

This approach will work as long as you do not write to the file any strings with commas in 
them. If there are, you will either need to use LINE INPUT or write these as'quoted strings', 
ie. strings surrounded with double quote characters (internal value 34), as follows: 

PRINT i1e.CHR!(34);address!(i):CHR$(34) 







The graphics facilities in BASIC 2 Plus allow you to draw a wide range of graphics effects, 
including lines, circles, boxes, pie sectors, etc. They can be drawn directly onto the screen or 
they can be output to a graphics device such as a plotter or graphics printer. Text can be freely 
mixed with graphics. 

Graphics output can also be sent to a file (known as a metafile) before being output to a 
graphics device. However, metafiles cannot be read into BASIC 2 Plus; they can only be 
written for use by another program. 

Graphics can be drawn in several colours (or intensities), line styles and line widths. Closed 
figures (such as circles or polygons) can be drawn as outlines or solids filled with a variety of 
patterns. 

A particular feature of graphics in BASIC 2 Plus is the ease with which the same graphics can 
be drawn on different devices with different characteristics. Two aspects of BASIC 2 Plus 
contribute to this: 

• the system of using streams to route output to different devices: this means that the only 
change you need to make to send the same commands to another device is to change the 
stream number, and 

• the definition of the shapes etc. that you want in terms of the ‘user coordinates'. The user 
coordinates on each device can readily be set up so that the same commands produce 
identical graphics on different graphics devices. Very different commands would be 
needed if the shapes had to be expressed in terms of the physical characteristics of the 
output device. 

These two factors mean that once the user coordinate systems have been set up appropriately, 
the stream number is the only difference between the commands used to output a particular 
graphic design on the screen and those used to output the same design on, say, a graphics 
printer. This is a key feature of BASIC 2 Plus graphics. 

Depending on the device, the output you send to a graphics device may not be acted upon 
immediately but instead saved up until the command: 

GRAPHICS [Itstream-number ] UPDATE /NEW7 

The effect of NEW depends on the device. For example, on a bit-image printer or a drum 
plotter, it will advance the paper at the end of the output. Refer to the guides supplied with the 
device for details. 
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GRAPHICS...UPDATE 

Use GRAPHICS-UPDATE forces graphics output to be acted on. 

Syntax GRAPHICS ffistream-numbeif, )] UPDATE /NEW ] 

Description With some graphics devices (but not Graphics Screens) output is stored and not 
acted on until the stream is closed. GRAPHICS-UPDATE forces all output so far to 
be acted on. Where it is relevant the NEW qualifier further causes a page throw, so 
that all further output is drawn on a fresh sheet. 


12.1 Principles of drawing graphics 

All graphics are drawn on a grid of points - typically a very fine one. 

The spacing of this grid both widthways and lengthways is defined by the coordinate system 
that is used. 

BASIC 2 Plus recognises two separate coordinate systems when handling graphics devices 
and graphics output - Device coordinates and User coordinates. 

Device coordinates are based on the device's 'pixels', that is to say, the smallest picture 
elements that the device can resolve separately. On a display, the pixels arc the individual 
phosphor dots that the display can make either bright or dark to produce an image. On a dot 
matrix printer, the pixels are the dots produced by the individual pins striking the ribbon. 

User coordinates are not based on any physical aspect of the graphics device but are set up to 
give you whatever number of grid points you choose both widthways and lengthways across 
the device area. In other words, user coordinates are set up in whatever way best suits your 
program (though there is a limit on how coarse a grid you define: the spacing cannot be 
greater than than one pixel). Moreover, you can readily make the spacing of the grid the same 
both widthways and lengthways, making it easy to specify shapes such as squares and circles. 

Warning! Some screens lie about the information they supply to BASIC 2 Plus. If BASIC 2 Plus is 
misled, user coordinates may not have the size or aspect ratio you expect. This could mean 
that squares will appear oblong and circles will appear oval. It could also invalidate much of 
what is explained in this section. 
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Chapter 12: Graphics 

Whenever you are drawing graphics, the coordinates to work with are user coordinates. 
BASIC 2 Plus ultimately uses device coordinates to draw the graphics but user coordinates 
are always used in the commands that specify the shapes and positions that are required. 

(Device coordinates would be not convenient to express the shapes etc. that you want in your 
program. For a start, the size of the pixels depends on the device itself: for example, on a 
CGA screen there are 640 pixels by 200; on a Hercules screen, there are 720 by 348; on a 
laser printer with a resolution of 300 dots per inch, the.pixels are one three-hundredth of an 
inch square. Output on different systems would therefore need to be specified individually. 
Moreover, as you see, the pixels aren't necessarily the same size widlhways as lengthways, 
making the grid more tightly spaced in one direction than in the other this would make it 
difficult to express squares and circles clearly.) 

When any graphics device is initially defined, BASIC 2 Plus automatically sets up a user 
coordinate system that gives you 3000 grid points along the shorter side of the drawing area 
and sets the number of grid points on the longer side so that horizontal user coordinates 
correspond to the same real distance as vertical. (If this would give more than 32767 grid 
points on the longer side of the grid, the longer side is set to 32767 and the smaller side is set 
in proportion. There are then fewer than 5000 grid points along the shorter side.) The origin is 
defined as the bottom lefthand comer of the grid. 

The area of Results-1 which you see displayed on the screen initially is approximately 5000 
user coordinates square. 

If the grid this gives is suitable to work with, there is no need to change it Changes only need 
to be made where this size of grid is not convenient for the graphics you want to draw (or the 
values you want to represent graphically) or to make the user coordinates on the different 
output devices compatible so that identical graphics can be produced on each even though 
they have different widths and heights. With compatible user coordinate systems on the 
different devices, exactly the same commands can be used to produce the graphics on each 
device despite differences in their physical sizes and pixel sizes. 

Positions are specified in user coordinates as horizontal;vertical, giving the number of 
horizontal and vertical user coordinates away from the 'user origin' (0;0), which is initially 
the bottom left comer of the virtual screen (but see USER ORIGIN). 

Note that the grid and the origin you choose must accommodate every position you will want 
to specify. Specifying positions outside the grid area generates an error. 
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12.2 Setting up the coordinate system 

The coordinate system that you set up determines the user coordinates that arc used for 
graphics output commands. 

When a graphics device is opened, user coordinates are automatically defined so that 
graphics will be corrccUy proportioned, correcting for any asymmetry in the pixels. This is 
done by treating the device area as a rectangle, whose shorter edge is 5000 user coordinates 
long; the length of the longer edge is automatically set to adjust for the physical difference. 
The graphics origin is initially set to the bottom left comer of the graphics screen. Thus, you 
can always imagine that you are drawing graphics on a square 'drawing space' of 5000 x 5000 
user coordinates. The same approach is used for all graphics devices, making it very simple 
for you to switch between them. 

While this will be entirely satisfactory for most graphics output, you can redefine the size of 
user coordinates (scale them) and redefine the origin as follows. 

Changing the scaling 

To change the size of user coordinates, use the command USER S PACE: 

USER [ft stream-number .] SPACE width, height 

This defines the dimensions of the graphics device’s drawing space as width user coordinates 
• wide and height user coordinates high; it also resets the origin to the bottom left comer of the 
drawing space. These dimensions must be greater than or equal to the width and height of the 
device (in pixels), and less than or equal to 32767. For example, you might define the 
Results-1 screen (640 x 200 pixels) to be 1000 units across and 750 units up by using the 
command: 

USER SPACE 1000, 750 

Note that the USER SPACE command given above will probably give you distorted 
graphics. (You can find out how distorted by using the function YASPECT - see below.) If 
you want to preserve symmetry, you can work out the width and height to set if you know 
physical size of the drawing space. But it is very much easier to leave most of the work to 
BASIC 2 Plus, and specify just one dimension in the USER SPACE command: 

USER ttstream-number. SPACE dimension 

This sets the user coordinates for the shorter axis to dimension and adjusts the user coordinates 
for the other axis to produce an aspect ratio of 1:1, automatically. 

For example, to specify a drawing space of approximately 10000 by 10000 user coordinates 
which does not distort graphics, use: 

USER SPACE 10000 
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Changing the graphics origin 

The graphics origin is initially defined as at the bottom left comer of the drawing space. It can 
be redefined using USER ORIGIN: 

USER [ftstream-numberj ORIGIN r,y 

x and y specify the new origin, relative to the bottom left comer of the drawing space, in user 
coordinates. This has no effect on output already in that space, but will effectively shift any 
subsequent output 

After moving the origin, it may be necessary to use negative coordinates. 


The origin is reset to the bottom left comer when the user coordinates axe redefined. (In the 
case of a graphics screen, it is also reset if the characteristics of this screen arc redefined using 
SCREEN GRAPHICS - see Chapter 9.) 



USER...SPACE 

Use 

USER_SPACE sets the extent of the user coordinate space. 

Syntax 

where 

USER [tfstream-number] SPACE width[. height] 

width and height are integer-expressions, giving positive, non-zero values. 

Description 

All graphics output is expressed in terms of "user coordinate's. The USER-SPACE 
statement sets the number of user coordinate points there are to be across and 
up the device. If only width is specified then user coordinate space is set to be that 
size along the shorter side - the size along the longer side is set so that points in 
the user coordinate space are square. 


Note that there must be at least as many user coordinates as there are device 
pixels, and this statement quietly enforces this restriction. 


USER...ORIGIN 

Use 

USER-ORIGIN changes where the origin of user coordinate space. 

Syntax 

USER $ stream-number] ORIGIN point 

Description 

By default the origin of user coordinate space is at the bottom left of the drawing 
surface. This statement moves the origin to the point specified. Note that this point 
is a position in user coordinates measured from the bottom left of the drawing 
surface - irrespective of the current origin. 
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Determining the current coordinate system 

On a graphics screen, two functions - X VIRTUAL and Y VIRTUA L - are provided to give you 
the width and the height of the drawing space in user coordinates: 

width - XVIRTUALft Weam-number)] 
height- Y VI RTUA l/( listream-numbei)] 

The same values can be determined in pixels by using the functions XDE VICE and Y DE VICE. 
XDEVICE and YOEVICE return the width and the height of the of the device area in pixels, 
andXPIXELandYPIXEL return the width and height of one pixel in user coordinates. 

You can also find out how distorted the drawing space is by using the function YASPECT: 
result - YASPECT/( #stream-number)] 

result is (user coordinate height)/(user coordinate width). If the drawing space is symmetrical, 
the result will be 1. 

12.2.1 Matching the coordinate systems 

Where the same graphics are to be output on a number of different graphics devices, it is 
important to have user coordinate systems that match on the different devices. In particular, 
you will want to ensure that: 

• the devices have compatible grid areas so that the positions used to draw the graphics on 
one device are also available on the device(s) on which the graphics are reproduced 

(specifying positions outside the grid area causes an error) 

• you may also wish to arrange that the physical size of the graphics is the same whichever 
device it is output on. 

Compatible grid areas 

Multiple user coordinate systems with identical grid areas can be set up simply by using the 
same USER SPACE width, height command to define the user coordinates on each graphic 
device (see 'Changing scaling' above). However, while squares may be truly square on one of 
the devices so set, they arc very likely to be distorted on all the others. 

If it is important that the graphics are not distorted, then you should use the statement USER 
SPACE dimension with just one parameter. 
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XVIRTUAL & YVIRTUAL 

Use 

The XVIRTUAL, YVIRTUAL functions return the size of a graphics virtual screen 
in user coordinates. 

Syntax 

XVIRTUA L(( [[[[stream-number) ] 

Y VIRTU A L/( [[[[stream-number) ] 

Description 

XVI RTUAL returns the width of the screen, YVIRTUAL returns the height. 


XDEVICE & YDEVICE 

Use 

The XDEVICE, YDEVICE functions return the size of a graphics device in device 
pixels. 

Syntax 

XDEVIC E[([[[]stream-number)[ 

YDEVICE(( [i[[stream-number) ] 

Description 

XDEV ICE returns the width of the graphics device, YDEVICE returns the height. 


XPIXEL & YPIXEL 

Use 

The XPIXEL,YPIXEL functions return the size of a device pixel in user i 

coordinates. 

Syntax 

X PIX E L(( / [[[stream-number) ] 

Y PIX E L/( [[[[stream-number) ] 

Description 

XPIXEL returns the width of the device pixel, YPIXEL returns the height. 

YASPECT 

Use 

YASPECT is a function which gives the aspect ratio of a user coordinate pixel. 

Syntax 

Y AS P ECT/( [[[[stream-number)] 

Description 

YASPECT returns the ratio of the height of a user coordinate to its width. 


If YASPECT is 1 then a box n x n will be square (provided as XMETRES and 

YMETRES returned by the device are correct). If YASPECT is greater than 1 then 
the box will be taller than it is wide. If YASPECT is less than 1 then the box will be 
wider than it is tall. 
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To produce graphics on different graphics devices that match in size, you need to make the 
user coordinates on each device represent the same scale. The easiest way to ensure this is to 
arrange that the user coordinates on each device are to a particular scale, such as ten user 
coordinates to a millimetre. 

The functions to use here, in general, are XMETRES and YMETRES which return the width 
and height of the display area in metres: 

device-width - XMETRES [(Ifstream-numbei)] 
device-height = YMETRES [(ttstream-numbei)] 

Multiplying these values by the number of user coordinates per metre you require then gives 
the numbers to be used as the width and the height in the appropriate USER SPACE 
command. 

For example, to get 10 user coordinates per millimetre, the number to multiply by is 10000. 
So the USER SPACE command to use is: 

USER [ft stream-number] SPACE 10000*device-width, 10000*device-height 

Note that this will also correct any display asymmetry, regardless of any previous use of 
USER SPACE for this graphics device. 

The only case where the above procedure is not suitable is where user coordinates are to be 
set for a virtual screen that doesn’t cover the full area of the display (see SCREEN GRAPHICS 
command in Chapter 14). The values returned by XMETRES and YMETRES for the screen give 
the full dimensions of the display, rather than the dimensions of the virtual screen. 

Equivalent dimensions for the virtual screen can, however, be calculated by multiplying the 
width and the height of the virtual screen in pixels as defined in the SCREEN GRAPHICS 
command by the width and height of a single pixel in metres. 

The size of a single pixel is readily obtained by dividing the full widll^cight of the screen in 
metres (as given by the functions XMETRES and YMETRES) by the same dimensions in pixels 
(as given by the functions XDEVICE and YDEVICE). A pixel's dimensions in millimetres (for 
the default screen) arc therefore: 

pixel-width - 1000 * XMETRES/XDEVICE 
pixel-height = 1000 * YMETRES/YDEVICE 

If the graphics screen had been defined as gwi d th pixels by g hei g h t pixels, its dimensions 
in millimetres would be: 

screen_width = gwidth*pixel_width 
screen_height - gheight*pixel_height 
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XMETRES & YMETRES 

Use The XMETRES, YMETRES functions return the size of a graphics device in 
metres. 

Syntax XMETRES/( Upstream-number)] 

YMETRES^ Upstream-number) ] 

Description XMETRES returns the width of the graphics device, YMETRES returns the height. 


Since you want a scale of 10 user coordinates to a millimetre, you want to define the USER 
SPACE as 10 limes the screen size in millimetres: 

USER SPACE 10*screen_width. 10*screen_height 

Again, any display asymmetry will automatically be corrected by this command, regardless 
of previous use of USER SPACE for this graphics screen. 

12.3 Standard graphics 

BASIC 2 Plus provides commands for drawing a range of graphics objects. The graphics 
objects that can be drawn with single commands are: 

• points and markers 

• straight lines 

• rectangles 

• polygons 

• circles and parts of circles 

• pie segments 

• ellipses and elliptical pie segments 

These graphics can be drawn in a variety of colours (or intensities on a monochrome 
monitor), line styles and line widths. Closed figures (such as circles and polygons) can be 
drawn as either as oudincs or as solids filled with various patterns. 



Various concepts appear so frequently in graphics commands that they arc defined separately 
and then used where necessary. 
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Points 


A point is specified in graphics commands may be 

xhy] 

or ;y 

where x and yare integer-expressions giving the distance in user coordinates from the screen's 
graphics origin, in the horizontal and vertical direction respectively. If either parameter (or 
both) is omitted, the position of the graphics cursor will be used instead. 

When more than one point is needed, points is used to signify a sequence of points separated 
by commas: 

pointl , point] ... 

All the points specified must lie within the drawing space, or an error will result. 


Styling options 

Graphics commands can end with a sequence of styling options. These specify details of the 
style of the object to be drawn, such as colour. 

They consist of keywords, sometimes followed by integer expressions. They can be omitted 
or supplied in any order, and are separated by spaces or other punctuation. 

Any aspects of the style which are not stated explicitly by the optional parameters will default 
to those in the default graphics style (which can be changed with the GRAPHICS command: 
see the section below on Default Graphics Style). 

There are three kinds of styling options: fill-options, line-options, and general-options. They are 
defined in Section 12.3.2 'Graphics styling'. 

12.3.1 The standard shapes 

The following describes the various commands available for drawing shapes. These 
commands are grouped according to the type of shapes they draw. There are thus sections on: 

• points and lines 

• polygons (including regular shapes such as rectangles), and 

• rounded curves and figures 

The commands given below include the various optional styling keywords that may be used 
with the command. These are explained in a separate section on 'Styling' below. 

Note that all the commands shown below are single commands: they arc shown split over two 
or more lines because of the limitations of the printed page. 



Points and lines 
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To plot a single point or series of points with markers, use the command PLOT: 

PLOT [ft stream-number,]points /MARKER marker-type] /SIZE marker-size]] 

general-options ] 

This plots markers centred on the points specified. 

The first two optional keywords allow you to control the type and the size of the markers that 
are used as follows: 

marker-type is an integer-expression which determines the style of marker used marker-types 1 to 
6 are defined as a dot, plus, asterisk, square, diagonal cross and diamond. Other types may be 
available depending on your computer. 

marker-size is an integer-expression which determines the size of the marker used. If the size 
specified is not available, the next smaller size available is used. 

To draw straight lines, use the command LINE: 

LINE [If stream-number,] points [ general-options ] [ line-options] 

This draws a line between each point specified. For example, to draw a triangle: 

LINE 2000:2000. 2000:4000. 4000:2000. 2000:2000 
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PLOT 

Use P LOT plots "markers" at the points given. 

Syntax PLOT (l)stream-number, J point [. point)...[[.] attribute)... 

where attribute is: MARKER marker-number 
or: SIZE marker-size 
or: COLOUR colour-number 
or: COLOR colour-number 
or: MODE write-mode 

Description PLOT draws a marker at all points specified. The attributes specify values to be 
used instread of the values last set in GRAPHICS statement. 

LINE 

Use LINE draws a line between two points, possibly via intermediate points. 

Syntax LINE tf)stream-number, ] point, [point.) ...point [[.] attribute] ... 

where attribute is: WIDTH line-width 
or: STYLE line-style 
or: START line-start-style 
or: END line-end-style 
or: COLOUR colour-number 
or: COLOR colour-number 
or: MODE write-mode 

Description LINE draws a line starting at the first point and ending at the last, passing through 
any intermediate points. The attributes specify values to be used instread of the 
values last set in GRAPHICS statement. 
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Polygons 

To draw any polygon, use the command SHAPE: 

SHAPE [iistream-number,] points [general-options] [line-options] [ifill-options ] 

This command draws lines between each specified point, finishing by drawing from the last 
point back to the first 

For example, to draw a solid diamond: 

SHAPE 3000:0, 2000:2000, 3000:4000, 4000:2000 FILL ONLY WITH 1 

The SHAPE command can be used to draw any polygon but where you simply want to draw a 
rectangle with horizontal and vertical sides, the command to use is BOX: 

BOX [itstream-number,] x\y, width, height /’R0UNDED7 [general-options][line-options] [ 

fill-options] 

This draws a rectangle with its bottom lefthand comer at r.y, giving it the specified width and 
height, then filling it if required. The optional keyword ROUNDED produces a rectangle with 
rounded comers. 


SHAPE 

Use SHAPE draws a polygon shape. 

Syntax SHAPE [{[stream-number, ] point, point, point [. point] ...([,] attribute] ... 

where attribute is: FILL/ONLY;/WITH fill-style] 
or: WIDTH line-width 
or: STYLE line-style 
or: COLOUR colour-number 
or: COLOR colour-number 
or: MODE write-mode 

Description SHAPE draws a line starting at the first point, passing through all the other point, 
and ending back at the first point. The inside is filled if FILL is specified. The line 
around is omitted if ON LY is specified with the FILL. The remaining attributes 
specify values to be used instread of the values last set in GRAPHICS statement. 
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BOX 

Use BOX draws a box on a graphics device. 

Syntax BOX fitstream-number, ] point, width, height [[,] attribute]... 

where attribute is: ROUNDED 

or: FILL /ONLY;/WITH fill-style] 
or: WIDTH line-width 
or: STYLE line-style 

or: COLOUR colour-number (or: COLOR colour-number) 
or: MODE write-mode 

width and height are integer-expressions, giving positive, non-zero values. 

Description BOX draws a box whose bottom left hand corner is at the point. The box is 
height wide and height high - where these are values in user coordinates. 
The box is drawn with rounded corners if ROUNDEO is specified. The box is 
filled if FILL is specified. The line around the box is omitted if ONLY is 
specified with the FILL. The remaining attributes specify values to be used 
instread of the values last set in GRAPHICS statement. 


For example, to draw a filled square with rounded comers: 
BOX 500:500, 4000, 4000 ROUNDED FILL WITH 3 
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Circles and Ellipses 
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To draw a circle or part of a circle, use the CIRC LE command: 

CIRCLE [IIstream-number,] x,y, radius /'PART start-angle,end-angle] 

[general-options] [line-options] [till-options ] 

This draws a circle (or a part of one) with its centre at x,y and the specified radius and fills it 
if required. 

A full circle is drawn unless PART is specified, whereupon just the section between start-angle 
to end-angle is drawn. These angles are specified in an anticlockwise direction, with 0 being 
along the positive x axis ('East'): (The units usually used for angles are radians, but see 
OPTION DEGREES.) 




CIRCLE 

Use CIRCLE draws part or all of a circle on a graphics device. 

Syntax CIRCLE [tistream-number, ] point, radius [[,] attribute] ... 

where attribute is: PART start-angle, end-angle 
or: FILL /ONLY//WITH fill-style] 
or: WIDTH line-width 
or: STYLE line-style 
or: START line-start-style 
or: END line-end-style 

or: COLOUR colour-number {or. COLOR colour-number) 
or: MODE write-mode 

radius is an integer-expression, giving a positive, non-zero value. 
start-angle, end-angle are numeric-expressions, giving positive, or zero, values. 

Description CIRCLE draws all or part of a circle whose centre is at the point. The circle has a 
radius of radius - where this is a values in user coordinates. The whole circle is 
drawn unless PART is specified. If part of the circle is to be drawn the part is 
specif ied by two angles measured anti-clockwise from the x-axis - start-angle and 
end-angle are those angles expressed in the current measure (radians or degrees). 
The circle is filled if FILL is specified. The line around the circle is omitted if ONLY 
is specified with the FILL. The remaining attributes specify values to be used 
instread of the values last set in GRAPHICS statement. 


r/9) 


BASIC 2 Plus: Language Reference 











For example: 


B2PLUS 


CIRCLE 2500:2000, 1500 


file View Progran Debug Edit Search Window 


h| Dialogue 

♦ Results-1 

Direct Cocnand; Clear 



circle 2500;29O8, 1508 [ 

3 

r f 

\ 

1 1 | 


\ 1 

Enjity Pi'ojp'/W 

\ J 


V_y < 





F- 

F^ 

F: 

wrZ 
j*r - 



wo 


































Chapter 12: Graphics 


Note that while all points specified in graphics commands must lie within the virtual screen, 
you may draw figures such as circles even if part of them would lie outside the virtual screen. 
This may however not be true when using other graphics devices. 

To draw a pie segment (sector of a circle), use the command PIE: 

PIE [it stream-number,] r,y, radius, start-angle, end-angle [general-options] 

[line-options] [fill-options ] 

This draws an arc centred on x,y, with the specified radius, from start-angle to end-angle, then 
draws radii to the ends of the arc and fills it if required. 


PIE 

Use PIE draws a circular "pie" section on a graphics device. 


Syntax PIE [Itstream-number, ] point, radius, start-angle, end-angle ([.] attribute]... 

where attribute is: FILL /ONLY;/WITH fill-style] 
or: WIDTH line-width 
or: STYLE line-style 

or: COLOUR colour-number{or: COLOR colour-number) 
or: MODE write-mode 
radius is an integer-expression, giving a positive, non-zero value. 
start-angle, end-angle are numeric-expressions, giving positive, or zero, values. 

Description PIE draws part of a circle whose centre is at the point, and joins the ends of the 
arc to the centre. The circle has a radius of radius- where this is a values in user 
coordinates. The arc is specified by two angles measured anti-clockwise from the 
x-axis - start-angle and end-angle are those angles expressed in the current measure 
(radians or degrees). The inside is filled if FILL is specified. The line around is 
omitted if ONLY is specified with the FILL. The remaining attributes specify values 
* to be used instread of the values last set in GRAPHICS statement. 
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Ellipses 


There are also elliptical versions of CIRCLE and PIE. These commands are E LLIPSE and 
ELLIPTICAL PIE. They behave exactly like the non-elliptical versions, except that aspect is 
added after radius in each case ie: 

ELLIPSE fttstream-numberj x;y, semi-axis, aspect fP ART start-angle,end-angle]{ 

general-options] [line-options] [fill-options ] 

ELLIPTICAL PIE /#, stream-number,]x-,y, semi-axis, aspect, start-angle, end-angle [ 

general-options] [line-options] [fill-options ] 

semi-axis is the semi-axis in the X dimension . aspect is a positive number (usually not an 
integer) which gives the ratio of semi-axes, so the radius in the Y dimension is taken as semi¬ 
axis* aspect 


ELLIPTICAL PIE 

Use ELLIPTICAL PIE draws a elliptical "pie" section on a graphics device. 

Syntax ELLIPTICAL PIE /// stream-number, J point, x-radius, start-angle, 

end-angle, aspect [[,] attribute]... 

where 


Description 


attribute is: FILL /ONLY/ /WITH fill-style] 
or: WIDTH line-width 
or: STYLE line-style 

or: COLOUR colour-number (or: COLOR colour-number) 
or: MODE write-mode 

x-radius is an integer-expression, giving a positive, non-zero value. 

aspect is a numeric-expression, giving a positive, non-zero value. 

start-angle and end-angle are numeric-expressions, giving positive, or zero, values. 

ELLIPTICAL PIE draws part of a ellipse whose centre is at the point, and joins 
the ends of the arc to the centre. The ellipse has a radius in the x-axis direction 
of x-radius - where this is a values in user coordinates - and a radius in the y-axis 
direction of x-radius * aspect. The arc is specified by two angles measured anti¬ 
clockwise from the x-axis - start-angle and end-angle are those angles expressed in 
the current measure (radians or degrees). The inside is filled if FILL is specified. 
The line around is omitted if ONLY is specified with the FILL. The remaining 
attributes specify values to be used instread of the values last set in GRAPH ICS 
statement. 
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ELLIPSE 

Use ELLI PSE draws part or all of an ellipse on a graphics device. 

Syntax ELLIPSE /// stream-number, J point, x-radius, aspect [[,] attribute]... 

where attribute is: PART start-angle, end-angle 

or: FILL /ONLY//WITH fill-style] 

or: WIDTH line-width 

or: STYLE line-style 

or: START line-start-style 

or: END line-end-style 

or: COLOUR colour-number (or: COLOR colour-number) 

or: MODE write-mode 

x-radius is an integer-expression, giving a positive, non-zero value. 

aspect is a numeric-expression, giving a positive, non-zero value. 

start-angle, end-angle are numeric-expressions, giving positive, or zero, values. 

Description ELLI PSE draws all or part of a ellipse whose centre is at the point. The ellipse has 
a radius in the x-axis direction of x-radius- where this is a values in user 
coordinates - and a radius in the y-axis direction of x-radius * aspect. The whole 
ellipse is drawn unless PART is specified. If part of the ellipse is to be drawn the 
part is specified by two angles measured anti-clockwise from the x-axis - start- 
angle and end-angle are those angles expressed in the current measure (radians or 
degrees). The ellipse is filled if FILL is specified. The line around the ellipse is 
omitted if ONLY is specified with the FILL. The remaining attributes specify values 
to be used instread of the values last set in GRAPHICS statement. 


BASIC 2 Plus: Language Reference 



















12.3.2 Graphics Styling 

The graphic shapes described above can all be drawn in a variety of colours (or intensities on 
a monochrome monitor), line styles and line widths. Closed figures (such as circles and 
polygons) can be drawn either as outlines or as solids filled with various patterns. 

The styles etc. used for each object drawn can be controlled through the optional keywords 
that can be included in the drawing command. If any style of graphics isn't specifically 
mentioned then the default for this aspect of style is used. 

The styling options fall into three groups: 

• general-options (which can be used with any type of shape) 

• line-options, and 

• fill-options 

The options are described below in these groups. 

General options: COLOUR and MODE 

general-options is 

/COLOUR colour ]/MODE write-mode] 

These options allow you to control the colour used for the graphic and its effect on the part of 
the screen on which it is written. 

colour is an integer-expression, which determines the colour (intensity) of the graphic; colour 0 
(white) and 1 (black) are always available; others depend on your computer. The colour 
codes are specified by GEM. 

Some graphics (dashed lines, for example) are drawn as a foreground (the dashes) 
interspersed with background (the gaps between the dashes). Normally both foreground and 
background are drawn, so that anything under the dashed line is obliterated, even if it lay in 
the gaps between the dashes. This can be changed by specifying a different write-mode, write¬ 
mode is an integer-expression in the range 1 - 4: 

1 Replace mode. Draws 'over' the current screen contents, so that parts of the object which 
are in the background (normally white) will be drawn, as well as the parts that are in the 
foreground. 

2 Transparent mode. Draws the foreground parts of the object only; parts in the background 
colour will not be drawn. 

3 XOR mode. Draws the foreground parts only, as new-colour XOR old-colour. This can be 
used, for example, to erase an object by plotting it again. 

4 Reverse transparent mode. Draws the background parts of the object only, in the 
foreground colour, producing a sort of 'negative' effect. 
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Line options: STYLE, WIDTH, START and END 

line-options is 

/STYLE line-style]l WIDTH line-width]] START line-start]] END line-end] 

STYLE and WIDTH can be used to define the width and style of line in any command that 
draws a line on the screen. START and END allow you to define the shape of the ends of lines 
that do not form a closed shape. 

line-style is an integer-expression which determines whether the line should be continuous, 
dotted, dashed etc. line-styles 1 to 6 are always available. (Other line-styles may also be 
available, depending on the device.) 

Dotted and dashed lines often can be drawn only if the line width is set to 1. This limitation is 
determined by the software used to drive your graphics device. 



line-width is an integer-expression which determines the thickness of the line, in pixels, after 
being rounded down to the nearest odd number. 

line-start and line-end are integer-expression in the range 0-2. They define the style used for 
each end of the line: squared, arrow and rounded, respectively. 

Fill options: FILL/ONLY; 

fill-options is 

FILL /ONLY/ [ WITH fill-style] 


FILL /ONLY/ WITH fill-style specifies that a closed shape should be filled and specifies the 
pattern that is to be used. If WITH fill-style is omitted, then the default pattern is used. 



fill-style is an integer-expression specifying what to fill with. Various fill patterns may be 
available depending on the software used to drive your graphics device. 

If FI LL ONLY is specified, the shape will only be filled; no edge will be drawn. 
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Default graphics style 

The default graphics style is the style that is used if none is specifically commanded. 

The default graphics style can be changed using the GRAPH ICS command, as follows: 
GRAPHICS [^stream-number]options 

where options is a list of any of the following options, separated by spaces: 

COLOUR colour 
MARKER marker-style 
MARKER SIZE marker-size 
/LINE; WIDTH line-width 
/LINE; STYLE line-style 
/LINE; START start-style 
/LINE; END end-style 
FILL /WITH //STYLE Jfill-style 
MODE write-mode 
CURSOR cursor-type 

The significance of each option should be obvious from the previous description of the output 
command options. 


The default graphics style is set to an initial state when a graphics device is opened, and reset 
when the graphics screen is redefined or reset (CLS RESET). 
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Use 

Syntax 

where 


where 

Description 


Use 

Syntax 

Description 


GRAPHICS 

GRAPHICS sets graphics output attributes. 

GRAPHICS [[[stream-number] [[,] attribute]... 

attribute is: CURSOR cursor-type 

or: FILL /STYLE;/WITH;////-s/y/e 
or:/LINE; WIDTH line-width 
or: /LINE; STYLE line-style 
or: /LINE; START line-start-style 
or: /LINE; END line-end-style 
or: MARKER marker-number 
or: MARKER SIZE marker-size 
or: COLOUR colour-number 
or: COLOR colour-number 
or: MODE write-mode 

cursor-type is an integer-expression, giving a value in the range 1..3. 

GRAPHICS sets attributes which are used for graphics output, where those 
attributes are not otherwise specified. 

CURSOR selects one of three cursor forms for use when a cursor is shown on the 
virtual screen. If this is not a Graphics Screen then this is ignored. 

GRAPHICS...RESTORE 

GRAPHICS-RESTORE turns on or off window contents restore. 

GRAPHICS [[[stream-number], ]] RESTORE tmth-value 

For Graphics Screens output is recorded so that the contents of the window can 
be restored when, tor example, it is closed and re-opened. If this is not required it 
can be turned off using this statement with a truth-value of FALSE. 
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12.3.3 Filling areas of the screen 

To 'flood fill’ a bounded area of the screen, use the FLOOD command: 

FLOOD [ftstream-numberjpoint[, limit] (fill-options][general-options ] 

limit is an integer-expression in the range 0 to 15, specifying a (boundary) colour. The other 
parameters are as described in the section on 'Graphic styling'. 

This command fills a window with the specified or default fill style and colour, beginning at 
point and spreading out from that point in all directions. Filling only stops when the next pixel 
to be filled has a 'boundary' colour. If limit is specified, this is the 'boundary' colour, otherwise 
it is taken as the colour you are filling with. 


Ec= 

m 


Filling will only take place within that part of the screen visible in the window, so that point 
must be in the window for filling to occur at all. Filling will finish not only at the window 
edge, but if it meets the edge of another window. 



It follows that if you want to fill a picture 'correctly', you must make the window full size (ie. 
the same size as its virtual screen) and the top window (see WINDOW OPEN). 

To read the colour of a point being displayed in a graphics window, use the function TEST: 

result - ^stream-number,] point ) 

result is -1 if the specified point is not being displayed, otherwise it is the colour code for that 
point, in the range 0 -15. 


m 



FLOOD and TEST may not be available on your computer, they depend on the version of the 
underlying software that you are using. 
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Use 

Syntax 

ir £ 

where 

if® 



Description 

j 
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Use 

i 

Syntax 

1 

p 

Description 


IMPORTANT: 

F 



FLOOD 

F LOOD fills an area bounded by a given colour. 

FLOOD (ft stream-number, ] point, [, boundary-colour] {[,] attribute]... 

attribute is: FILL WITH fill-style 

or: COLOUR colour-number 
or: COLOR colour-number 
or: MODE write-mode 

boundary-colour is a colour-number. 

F LOOD fills an area bounded by pixels of a given colour. Filling starts at the point 
given. The bounding colour is boundary-colour, if given, otherwise the colour being 
filled with. 

TEST 

TEST is a function which returns the colour of a point on a Graphics Screen. 
TEST( [#stream-number, ] point) 

If the given point is visible then TEST returns the colour-number for the colour of the 
corresponding screen pixel - this is an integer greater than or equal to zero. 
Otherwise, TEST returns -1. 


version of the underlying software that you are using. 
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12.4 Turtle graphics 



As well as drawing graphics using the standard graphic commands already described, you 
can choose to use a number of simple graphics commands to drive a cursor around the 
drawing area, drawing as it goes. This type of graphics output may be familiar if you have 
used the programming language LOGO - it is usually called 'turtle graphics'. 

Turtle graphics are nothing like as sophisticated as the graphics drawn by the standard 
graphics commands. Where the standard graphics commands which provide 'ready-made' 
shapes, the individual turtle commands each either move the turtle forward in the direction it 
is pointing (drawing a line if required) or turn the turtle to point in a different direction. The 
shapes the turtle draws cannot automatically be filled (though you may be able to use FLOOD 
to fill these if your system supports this), but you can use the full range of line styles, colors 
and write-modes (see 'Graphic styling' above). 






When using turtle graphics commands to draw shapes on the screen on the screen, you can if 
you wish display the 'turtle'. The turtle you use is simply the screen cursor, shown in this case 
as a box with an arrow on it. The arrow is used to show the turtle's current heading (initially, 
0; to the right). The commands to use to display this cursor are: 

WINDOW [# stream-number ] CURSOR ON (if no cursor is currently being displayed) 
GRAPHICS [# stream-number] CURSOR 3 

While you can mix turtle graphics output with other graphics and text on the same screen, all 
output uses the same cursor, so you will have to control its position carefully. 



12.4.1 Pointing the turtle 


The turtle is turned to point in different direction by using the commands LEFT, RIGHT and jr- 
POINT as follows: ~ 


LEFT [itstream-number,]angle — 

makes the turtle turn through angle, anti-clockwise. LEFT may be abbreviated to LT. — 
(Angles will normally be in radians, but see OPTION DEGREES.) 


RIGHT [iistream-numberj angle 

makes the turtle turn through angle, clockwise. RIGHT may be abbreviated to RT. 



POINT [iistream-numberjangle 

This sets the direction of the turtle so that it points angle radians anti-clockwise of 
'due east'. 
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LT & RT & LEFT & RIGHT 

Use 

These statements change the current heading. 

Syntax 

LEFT [[[stream-number. ] angle-change 

LT [[[stream-number, ] angle-change 

RIGHT [[[stream-number, ]angle-change j 

RT [[[stream-number,, ] angle-change 

where 

angle-change is a numeric-expression. 

Description 

LEFT and LT add the angle-change to the current heading - so while facing in the 
direction of the current heading this is turning left. RIGHT and RT subtract the 
angle-change from the current heading - so turning right. The angle-change is in the 
current measure (radians or degrees). 

POINT 

Use 

POINT sets a new current heading. 

Syntax 

POINT [[[stream-number, ] angle 

where 

angle is a numeric-expression. 

Description 

POINT sets the current heading to the angle given, where that is in the current 
measure (radians or degrees). 


—12.4.2 Moving the turtle 

_—y. The turtle is moved forward in the direction it is currently pointing by using the FORWARD 

—P command: 



/M0VE7 FORWARD [Ilstream-numberJ distance [STYLE line-style] line-width] 

/START line-start] /END line-end] /COLOUR colour] /MODE write-mode] 

The FORWARD command moves the turtle forward distance user coordinates on its current 
heading. If MOVE is not specified, the turtle will draw a line as it goes. 

(FORWARD may be abbreviated to FD.) 
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FD & FORWARD 


Use 

FD and FORWARD move the cursor fotward a given distance. 

Syntax 

[MOVE] 

FORWARD $ stream-number, ] distance [[,] attribute]... 


[MOVE] 

FD [it stream-number, ] distance [[,] attribute]... 

where 

attribute 

is: WIDTH line-wdth 


or: 

STYLE line-style 


or: 

START line-start-style 


or: 

END line-end-style 


or: 

COLOUR colour-number 


or: 

COLOR colour-number 


or: 

MODE write-mode 


distance is an integer-expression, giving a positive, non-zero value. 


Description FD and FORWARD draw a line from the current position the given distance in the 
current heading. The attributes specify values to be used instread of the values 
last set in GRAPHICS statement. 

MOVE FD and MOVE FORWARD move from the current position the given distance in 
the current heading, without drawing anything. 


12.4.3 Information about the turtle 

Details such as the direction in which the turtle is currently pointing and how far it would 
have to move to get to a particular position on the screen can be obtained by using the turtle 
graphics functions HEADING, TOWARD and DISTANCE as follows: 

HEAD ING/( it stream-number)] 

returns the current turtle heading in radians relative to its starting direction ('due east*) 

T OWARD ( filstream-numberj x;y) 

returns the heading the turtle would have to point to to reach the position with user 
coordinates x;y 

DI STANCE! [it stream-number,] x\y) 

returns the distance the turtle would have to move to reach position x;y 
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HEADING 

Use 

HEADING is a function which returns the current heading. 

Syntax 

HEADINGS Upstream-number) ] 

Description 

HEADING returns the current heading as an angle, in the current measure 
(radians or degrees), measured anti-clockwise from the x axis. 


TOWARD 

Use 

TOWARD is a function which returns the heading from the cursor to a given point. 

Syntax 

TOWARD! [Ihtream-number. ] point ) 

Description 

TOWARD returns the heading from the current cursor position to point. The value is 1 
an angle anti-clockwise from the x axis, in the current measure (radians or 
degrees). 


DISTANCE 

Use 

DISTANC E is a function which returns the distance from the cursor to a given 
point in user coordinates. 

Syntax 

DISTANCE! [ihtream-number . ] point) 

Description 

DI STANCE returns the distance from the current cursor position to point. The value 
is in user coordinates. 


These functions can be used, for example, to draw from the current position to a particular 
position: 

POINT TOWARD(targetx:targety) 

FORWARD DISTANCE(targetx:targety) 
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12.5 Special features of text output on Graphics devices 

Graphics devices support all the text output facilities available for text screens, as well as 
providing a variety of other effects. In addition, you can position text more precisely on a 
graphics device because you are working in pixels rather than character cells. 

Text is output using a style which is a combination of a particular text font, text size, angle 
and write mode. As with output to a text screen, you can override the default style within a 
PRINT command by using print functions, or change the default style by using the SET 
command. The styles available, print functions and SET command are described below. 

12.5.1 Styling text on graphics devices 

As well as the facilities described for text screens, graphics devices provide these additional 
facilities: 

• a variety of text fonts 

• a variety of text sizes 

• angled text 

• a variety of write modes (replacing or writing over previous text!graphics) 

• with each line starting at a particular point (ie. indented) 

These extra facilities are described below. 


Colours and Effects 


You can specify COLOUR and EFFECTS when outputting text on graphics screens; these 
options work in exactly the same way as on text screens. 

You can also specify that text be printed in one of the four modes which are available for 
graphics commands: replace mode, transparent mode, etc. To do this, use the print function 
MODE ( write-mode) (where write-mode is an integer-expression in the range 1 - 4). For example: 

M0DE(4) : "This Is a heading" 

Note that in a PRINT command, write-mode is enclosed in brackets, unlike 'drawing' 
commands. 
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Using different fonts 

As well as the print effects (bold, skewed, etc.) described previously, text can be displayed in 
different typestyles, called fonts. BASIC 2 Plus numbers each of the fonts you can use, 
starting from 1. The standard system font (the one used on text screens) is always supplied for 
use on the screen; it is numbered 1. Other fonts may be available on your system and on any 
graphics device you use. For details of the fonts available on your system, see your other user 
guides. 

To discover the numbers and names of fonts you have available, either consult the guides 
supplied with it, or use the function FONTS: 

results- FONTS (fit stream,] font) 

results is either the name of font number font, or a null string if that font is not available. 

For example, to display the names of all fonts supplied. 

FOR fontno - 1 to 100 
names - FONTS(fontno) 

IF names - "" THEN EXIT FOR 
PRINT nameS 
NEXT fontno 

To print the following text in a different font, use the PRI NT function FONT: 

PRINT [lfstream,][itemsrj FONT (font)', ilems-2 

This will only affect the font used for the print-items in this PRINT command that follow the 
FONT print function (ie. items-2). 

While all fonts should display 'normal' characters (with codes in the range 32 - 127) as 
recognisable versions of the corresponding character in the standard system font, characters 
outside this range may or may not be displayed as similar characters (check your other guides 
for details). 


FONT$ 

Use FONT $ is a function which returns the name of a font. 

Syntax F0 N T $ ( (ihtrem-number. ] font-ordinal) 

where font-ordinal is an integer-expression, giving a positive, non-zero value. 

Description F0NT$ returns the name of the 'nth' font available on the device. If there is no 
such font a null string is returned. 
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Using different text sizes 


result = POINTS lll{ [^stream,]font,pointsize) 


=1 


Text can be printed in a variety of sizes, measured in 'points'. A point is 1/72 of an inch. The 
point sizes (ie. sizes of text, in points) available depend on details of your system and its 
fonts. You can find these out from the guides you have for your system, or by using the 
function POINTSIZE: 






result is an integer, the nearest smaller point size available for the font. If there is no such point 
size in this font, the result returned is the smallest point size available. 




You can use POINTSIZE to print all the point sizes available for a given font. The following 
shows you how to do this, using font number 1 as the example font: 




fontno = 1 
fontsize - 256 

PRINT "Point sizes for font "sfontno 
DO 

old_fontsize - fontsize 

fontsize = pointsize(fontno.fontsize-l) 

IF fontsize <> old_fontsize THEN PRINT TAB(6) ;fontsize 
REPEAT UNTIL fontsize - old_fontsize 




To print the following text in a different point size, use the PRI NT function POINTS: 
PRINT [ft stream,] [itemsj POlUJSi points): items-2 



Again, this only affects the point size used for the print items that follow this print function, p- 
ie. items-2. — 


Use 

Syntax 

where 

Description 


POINTSIZE 

POINTSIZE is a function which returns an available size of a font. 

POINTSIZE( [ftstream-number, ] font-ordinal, point-size ) 

font-ordinal and point-size are integer-expressions, giving positive, non-zero values. 

POINTSIZE returns an available point size available for the font given by font- 
ordinal. The value returned will be the largest available size which is less than or 
equal to the point-size specified - or the smallest available size if point-size is smaller 
than the smallest available. 
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Text is printed on the same base line regardless of changes in point size: 

Big Text LitdcText 

The vertical distance that the cursor moves at the end of a line depends on both the current 
text size and the default character size. It is calculated as the base-line to bottom-line distance 
for the current font and point size, plus the top-line to base-line distance for the default 
character size. t 


First Line 

Base Line 


Bottom Line 

Second Line 

Top Line 

Base Line 


Bottom Line 

It follows that if characters are in a larger point size than the default size then they may 

overlap the previous line. To avoid this, use the ADJUST print function instead of P01NTS in 


the part of the print statement that outputs the items on the second line: 
PRINT [ftstream,] [items\J ADJUST (.points): items-2 


For example: 

SET POINTS 10 

PRINT POINTS(18); "Major heading” 

PRINT ADJUSTU4); "Subheading" 

PRINT "Actual text" 

which would be displayed as: 

Major Heading 

Subheading 

Actual text 

(The third line of text does not need to be adjusted as it is in the default character size.) 

ADJUST makes the top line of the character cells used for the output in the new character size 
the same as the bottom line used for the previous line. This is automatically true for 
characters printed in the current character size. 
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Writing text at different angles 

Text is normally printed horizontally, but can be printed at any angle, by including the ANGLE 
print function in a print statement: 

PRINT fflstream,] [items-J ANGLE! angle); items-2 

angle is in degrees, regardless of the current angle option you have specified for angles used 
in numeric functions. 

With an angle of 90, as in: 

PRINT WstreamJ[items-J ANGLE(90); items-2 
the text will be printed vertically. 

The angles available are determined by your version of GEM. You will normally only be able 
to use angles that are multiples of 90 degrees. 


Changing the default styling 

You can change the text styling used in all subsequent print instructions (ie. the default text 
styling) by using the command SET, followed by the appropriate print functions), which this 
time don't have brackets around their parameters. 


The full specification of the SET command is as follows: 
SET fit stream] options 


where options is a list of any of the following options, separated by spaces. Any number of 
these can be set at any time and in any order in the instruction. 


ZONE zone-width 
COLOUR colour 
EFFECTS effects-1 
WRAP switch 


FONT font-number 
POINTS points 

ANGLE angle 
MODE write-mode 
MARGIN margin 


print zone width 
foreground colour 
[,effects-2] text style 

automatic carriage retum/line feed at right edge of screen 

(where switch is a numeric-expression giving 0 (to turn 

WRAP on) or a non-zero value (to tum WRAP off)) 

text font. This also resets the point size 

text size. The point size will be reset if you subsequently 

change fonts. 

text angle 

write mode 

text margin 


Note the difference between print functions in PRINT commands, which change the style 
temporarily (for the rest of the PRINT command) and print functions in SET commands, 
which change the style used as a default in all subsequent PRINT commands. 
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SET 

Use S ET changes the text output attributes for a given stream. 

Syntax SET ^stream-number].]] text-attribute R,Jtext-attribute]... 
where each text-attribute may be one of: 

ZONE integer-expression 

MARGIN integer-expression 

EFFECTS integer-expression, integer-expression 

MODE integer-expression 

COLOUR integer-expression 

COLOR integer-expression 

FONT integer-expression 

POINTS integer-expression 

ANGLE integer-expression 

WRAP integer-expression 

Description SET changes the attributes permanently. 



Use CLS clears a virtual screen. 

Syntax CLS [RESET] 

CLS [tfjstream-number [[,] RESETS 

Description C LS clears a virtual screen. If RESET is specified the attributes specified by SET 
are restored to their default values. 


On a graphics screen, you can return the default text style to its initial state by using: 

CLS fit stream] RESET 

This also clears the screen. (Note: The text style is automatically reset to its initial default 
state if the screen or its window is redefined using a SCREEN TEXT ora SCREEN GRAPHICS 
command). 
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12.5.2 Positioning the text 

Unless specified otherwise, the current character position is the character position 
immediately to the right of the last character to be printed (at whatever angle you are 
working), bearing in mind the pointsize you are using. 

There are various ways in which you can specify a different position for the next character to 
be printed. As on any output device, you can use commas between the items to start each item 
at the beginning of the next print zone; you can also use the TAB(x) print function to move the 
cursor position to column x, either on the same line or on the next line if the cursor position is 
already beyond the column. You also have the LOCATE and TEXT FEED commands and the 
AT print functions that you can use on text screens, and on a graphics screen you can use the 
control codes and escape sequences also described for text screens. 

The commands and print functions mentioned above are all based on a character grid of lines 
and columns, and character cells of the standard character cell size. On a graphics device, you 
can position the cursor much more precisely by specifying the position you require in user 
coordinates. 

To move the cursor to a position specified in user coordinates, use MOVE. 

MOVE HIstream,]xiy 

The position r,y will be used as the lefthand edge of the base line for the next character 
printed. 

To determine the current cursor position, use the following functions: 

result - XPOS [litstream)] 

- horizontal position, in user coordinates 

result- 'I POSH It stream)} 

- vertical position, in user coordinates 

result - POSf(IIstream)) 

- horizontal position, as row 

result - yPOSf(llstream)] 

- vertical position, as line 

With the variety of text fonts and sizes available, it can be quite difficult to position text 
exactly, for example when labelling a diagram or centring a line of text. You can convert 
positions and distances from text coordinates to user coordinates with the aid of the following 
functions, which give the dimensions of the standard character cell: 

result - KELL fill stream)] 
result - YCELL f(IIstream)] 
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POS & VPOS 

Use 

These function return the current cursor position in charactrers and lines. 

Syntax 

P0S/( [^stream-number) ] 

V P0Sf( [ipstream-number) ] 

Description 

POS returns the current character position. VPOS returns the current line position. 


XCELL & YCELL 

Use 

XC E L L and Y C E L L are functions which return the size of a character cell. 

Syntax 

XCELL/( [ipstream-number) ] 

YC E L L/( [ipstream-number)] 

Description 

XCELL returns the width of a character cell, YCELL returns the height. These 
values are in user coordinates. 


XPOS & YPOS 

Use 

XPOS and Y POS are functions which return the current cursor position. 

Syntax 

X P0S(( [ipstream-number)] 

YP0Sf( [ipstream-number) ] 

Description 

XPOS returns the position in the x dimension, YPOS returns the position in the y. 
These values are in user coordinates. 


:s 

:- 5 * 



cr-9 
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You can also determine the length of a piece of text by using the function EXTENT: 
result - EXTENT( [#stream,][print-functions,]string-expression) 

resultis the length in user coordinates that the string-expression would have, if the print-functions 
and string-expression were used in a PRINT statement. However, EXTENT cannot be used with 
print-functions and string-expression that include any cursor-moving facilities, such as AT. (The 
algorithm it uses for working out the length wouldn't give the right result) 


•• 










"EXTENT.:.. . ... 

1T ... 


Use The EXTENT function returns the length a string will be when printed. 

• g , ,. 

eam-mimher 1 strinn-ernressinnY 


. 


Syntax EXTENT ( fflstream-number, ] string-expression) 


or EXTENT ( fltetream-number(. jl print-function ([,]print-function]... [,]string-expression) 

Description EXTENT returns the length in user coordinates that the given string would be if it 
were printed on the given (or default) graphics screen. If any print-function s are 
given, then their effect is taken into account. 


. __ 



















Chapter 13 

Random & Keyed Files 




BASIC 2 Plus supports three types of data file: sequential files, random files and keyed files. 
Sequential files are the easiest to understand but are limited in scope. Keyed files are more 
complex than random files, but, once mastered, will help solve a surprising variety of data 
handling problems. 


Sequential files are used for storing data which need only be read starting at the beginning. 


going on to the end and then stopping. Sequential files cannot be changed directly, apart from 
appending to them. Sequential files are read using INPUT and written to by PRINT. These are 
described in the chapters on Text Input and Output 


Random files are organised in equal size records. Records are numbered. Records can be read 
and written in any order. New records can be added at any time. To access information held 
in a random file all you need is the appropriate record number - how you establish that is up 
to you. 

Keyed files are like random files but the records are refered to by 'name'. The 'name’s of 
records in a keyed file are called its keys. Keys are held in one of twenty separate indexes. To 
access information in a keyed file some property of the information itself may be used. So to 
find the telephone number for "Locomotive Software" (in a suitably organised file) you 
simply ask BASIC 2 Plus to read the record which has "Locomotive Software" as its key (in 
the appropriate index). Furthermore, the keys are always in order in the indexes, so you could 
very simply produce a listing of this telephone book in alphabetical order. 

Random files and keyed files are in many ways similar, the difference between them being 
simply the way in which records are referred to. This relationship is reflected in the facilities 
provided for these types of file. 

This chapter describes how to use random and keyed files. 
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13.1 Data in Random and Keyed Files 

Data in random and keyed files is held in equal size records, which are all equally acccssable. 
BASIC 2 Plus allows for up to 2,147,483,647 records in a file - though other limits may be 
met first! The length (in bytes) of each record is set for random files when the file is opened 
and for keyed files when the file is created. 

Records are read using GET and written using PUT. These operations transfer data between the 
file and string variables. So, for example: 

GET #7. a$ 

gets a copy of the contents of the record at the "current position" in the file open on stream 7, 
and assigns it to the string aS. (The "current position" is an important concept which is 
discussed shortly.) Further: 

PUT #7. aS 

puts the value of the string aS into the record at the "current position" in the file open on 
stream 7, replacing the previous contents of the record. 

BASIC 2 Plus's RECORD structures may be used to access data in a suing which has been read 
fromm, or is bound for, a random or keyed file record. The string is a simple copy of the 
amorphous data which may be given form and meaning by applying a RECORD structure to it. 
A simple telephone list might, for example, be handled thus: 

RECORD tel; names FIXED 30. number 
GET #7. aS 

PRINT aS.tel.nameS: aS.tel.number 

The file would contain 38 byte records (30 bytes for the name and 8 bytes for the number). 
The GET statement reads from a record in the file into the string aS, from which information is 
extracted using the RECORD structure. For this to make sense, the records in this file must 
have been written by a piece of program like this: 

RECORD tel; nameS FIXED 30. number 
a$.tel.nameS - "Locomotive Software" 
aS.tel.number = 740606 
PUT #7. aS 

Most operations on random and keyed files involve the "current position". For each stream 
on which a random or keyed file has been opened BASIC 2 Plus keeps a current posiuon. The 
current position is simply a pointer into the file, pointing at one of the records - the "current 
record". To access a record the current position must be set to point at the record. The 
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POSITION statement docs just that. So to position on the record for Locomotive Software (in 
a suitable keyed file) a statement of the form: 

POSITION #7 KEY "Locomotive Software" 

is required. The record can then be read and used as given above. 

The most straightforward way to use random and keyed files is to use POSITION to point at 
the required data and the simple forms of GET and PUT to read and write it. Because records in 
random and keyed files are refered to in different ways there are different forms of the 
POSITION statement - but the basic function is the same. 


13.2 Random files 


Records in random files are refered to by number, the record number. The first record is 
number 1, the second number 2, and so on. The current position for a random file is, 
therefore, simply the number of the current record. 

A random file can be thought of as an indefinite size (single dimensional) array of fixed 
length strings. POSITION selects an entry so that GET and PUT can transfer data to and from 
this "array”. 

To use a random file you must first open it on a stream. You can then read and/or write 
records. When you have finished with the file the stream must be closed. 



13.2.1 Opening and closing a random file 

Before you can use a random file, you must 'open' it, for example: 

OPEN #7 OLD RANDOM "c:\mine\telephon" LENGTH 38 

opens the file C:\MINEVTELEPHON (which must exist) on stream 7, and sets a record length 
of 38 bytes. 

The keyword OLD specifics that the file to be opened must exist. Using NEW here would 
specify that the file to be opened must not exist - so a new file is to be created and opened. If 
neither is specified then if the file exists it will be opened otherwise it will be created and 
opened. Creating a random file creates an empty file. 

The LENGTH clause may be omitted, in which case a length of 128 bytes is assumed. While it 
is possible to specify a different length every time a given file is opened the most likely result 
is confusion! 
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An existing file can be opened to read and change it. If you want to be sure to create an empty 
file, you can check if there is already a file with the same name and delete it if found (using 
FIND) and KILL, as described in Chapter IS file handling 1 ). But beware if you are writing a 
program for use on a multi-user system, as another user could re-create the file between the 
KILL and the OPEN! 

OPEN sets the current position to the first record in the file. 

A file stays open until you close the stream. You should not remove a disc containing an open 
file until it has been closed or information may be lost When you have finished with the file, 
close the stream using CLOSE (as used with all streams, see Chapter 8) for example: 

CLOSE #7 

which closes stream 7. 

Closing the stream closes the file. Closing the file writes away any buffered data, updates 
directories and so on. Once the file is closed the stream released, ready for something to be 
opened on iL 

13.2.2 The current position in a Random File 

The LOC function returns the record number of the record at the current position. For 
example: 

cr - L0C(#7) 

sets the variable cr to the number of the record at the current position in the random file open 
on stream 7. 

To change the current position two forms of the POSITION statement may be used, 
P0SITI0N_AT which sets the position to a given record, and P0SITI0N...NEXT which sets 
the position to the next record after the current For example: 

POSITION #7 AT 2300 

will set the current position in the random file open on stream 7 to be record number 2300. 
And: 

POSITION #7 NEXT 

will set the current position to the record following the current record, which is the same as: 
POSITION #7 AT L0C(#7)+1 

It is possible to set the current position to a record which has never been written to (even if 
this position is beyond the end of the file). Reading the record at this position will not fail, but 
the data returned is indeterminate. Writing to this position implicitly "creates" the record. 
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OPEN...RANDOM 

Use OPEN... RANDOM associates a given stream with a random or keyed file. 

Syntax OPEN fflstream-number [,] [exist] RANDOM random-spec [(.] LOCK lock-type] 
where random-spec is filename [[,] INDEX filename] [[,] LENGTH record-length] 
record-length is an integer-expression, giving a value in the range 1..4096. 

Description This statement without the INDEX clause opens the given file for random access. 

In random access the file is treated as an array of records referenced by record 
number, the first record in the file being record number 1. Each record is *n* bytes 
long, where ’n' is the given record-length, or 128 if no length is specified. 

This statement with the INDEX clause opens the given files for keyed access. In 
keyed access the file is treated as a collection of records referenced by one or 
more key values in one or more indexes. The first filename specifies the file 
containing data, the second filename specifies the file containing the indexes. If 
neither file exists then they are both created and empty indexes are constructed - 
the data file is set to have records is ’n’ bytes long, where 'n' is the given record- 
length (and must be at least 2), or 128 if no length is specified. If both files exist 
then they are both opened - if a record-length is given it must be the same as the 
length set when the file was created. It is an error if one of the files exists but the 
other does not. 

If the NEW exist option is present then the file (or files) must not exist. If the OLD 
exist option is present then the file (or files) must exist. 

If no lock is specified the file is opened write locked. 

OPEN-RANDOM opens a stream of Random File class. OPEN-RANDOM-INDEX 
opens a stream of Keyed File class. 
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POSITION 

Use POSITION moves to a new position in a Random or Keyed file. 

Syntax POSITION $]stream-number [,] position ([,] LOCK lock-type} 

where position is: NEXT 

or: AT record-number 
or: AT position-string 

or: KEY key-value [[,} INDEX index-number] 
or: INDEX index-number 

where key-value is an expression, giving a value compatible with the index’s key type. 
index-number is an integer-expression, giving a value in the range 1 ..20. 
position-string Is a string-expression, giving a value once returned by P0SITI0N$. 

Description POSITION may only be used with Random and Keyed Files. It moves to the 
position specified, if possible. 

POSITION-NEXT moves on to the next record in the file. POSITION-AT record- 
number may only be used with Random Fifes, where it moves to the given record. 
POSITI 0N_AT position-string moves to the position previously recorded in the 
position-string. 

POSITION-KEY-INDEX and POSITION-INDEX may only be used with Keyed 
Files. POSITION-KEY-INDEX moves to the first record with the given key value 
in the given index (or the current index if is none is given). If there is no record 
with the given key value, then the move is to the record immediately following the 
position where a record with the given key value would be - if there is no such 
record then the move is to "end of index". POSITION-INDEX moves to the first 
record in the given index. 

Once positioned any record lock specified is applied. If no lock is specified the 
new current record is temporarily write locked - this lock is removed if the position 
changes for any reason, or if it is replaced by an explicit lock. If the lock fails an 
error is raised, but the new position is still set. Note that no record locks are 
applied if the file itself is read or write locked. 

If the POSITION statement is assigned then the value returned is 0,1 or 2. 

Return values 1 and 2 indicate that the given key value did not exist: 1 means the 
new position is on the ’’nearest" record; 2 means the new position is "end of 
index". 
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■EOF 

' ' 

Use LOF returns the length of a file. 

: 

Syntax LO F ( $]stream-number) 

Description LOF may be applied to any File stream. It returns the length of the file in bytes. 

For Keyed File streams LOF returns the length of the data file. 

Note that if the file is actually a device-for example an input file "COM1 * - then 
LOC returns zero at all times. 




The LOF function returns the length of the file, in bytes, for example: 
filejength - L0F(#7) 

Dividing this by the record length, and taking the ceiling of that, gives the number of the last 
record in the file. For example: 

last_record - CEILING(L0F(#7) / recordjlength) 

(If the length of the file is not an exact multiple of the record length there is an incomplete 
record at the end of the file, this incomplete record is padded with zeros if it is read.) 


The EOF function (see ???) returns true if the current position is beyond the last record in the 
file. 


13.2.3 Reading records 

Records are read from a random file using the statement GET. For example: 

GET #7. rec$[21] 

which assigns to the variable rec*[21] a copy of the contents of the record at the current 
position in the file open on stream 7. 

The common pair of statements of the form: 

POSITION #7 AT want 
GET #7. rec$ 

may be elided into a single statement of the form: 

GET #7. recS AT want 
which has the same effect 

(Incidentally, it is also possible to write statements of the form GET #7. reel NEXT, which 
reads the record after the current position - but this is less obviously useful.) 
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The following example reads all the records in a trivial telephone directory and prints their 
contents: 

RECORO tel; name$ FIXED 30. number 
OPEN #7 RANDOM "telephon" LENGTH 38 
DO UNTIL E0F(#7) 

GET #7. reci 

PRINT rec$.tel .name); rec$.tel.number 
POSITION #7 NEXT 
LOOP 

CLOSE #7 


GET 

Use GET gets data from Random or Keyed Files. 

Syntax GET $]stream-number, string-general-variable [[,] position] [[,} LOCK lock-type} 
where position is as described in POSITION. 

Description GET may only be used with Random and Keyed Files. It reads a record from the 
file and assigns it to the given string-generai~variab\e. 

If no position is specified the data is read from the record at the current position. If 
a position is specified then it is acted on before the data is read - see POSITION 
lor a description of position -so the data is read from the new position. Note that 
with a Keyed File it is an error to specify a position which does not exist - the 
action is abandoned (producing an error) without affecting the current position or 
any temporary lock. 

If neither the file nor the (new) current record are read or write locked the record is 
temporarily read locked before the data is written - this lock is removed if the 
position changes for any reason, and if it is replaced by an explicit lock. If the lock 
fails the action is abandoned (producing an error), and nothing is read - note that 
any position has already been performed, so the position has changed. 

It a LOCK is specified the required record lock is aquired after the data is read. If 
the record was temporarily locked this lock replaces the temporary one. This may 
be used to unlock the record once if has been read. Note that no record locks are 
applied if the file itself is read or write locked. 

Note that for Random Files GET can read records which have never been written. 

It is not possible to predict what such records will contain. 


230 
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13.2.4 Updating a random file 

A random file may be updated in a number of ways: 

• replacing an existing record 

• amending an existing record 

• adding a new record 

In all cases PUT is used to write to the chosen record, for example: 

PUT #7, rec$ 

This writes the value of r ecS to the record at the current position in the file open on stream 7. 



Use PUT puts data to Random or Keyed Fires. 

Syntax PUT ^stream-number. string-expression ft.) position) ([,] LOCK lock-type] 
where position is as described in POSITION. 

Description PUT may only be used with Random and Keyed Files. It writes the data given by 
the string-expression to the tile. If there are fewer bytes of data than the record will 
hold the data is padded on the right with zeros. It is an error to attempt to write 
more than the record will hold. 

If no position is specified the data is written to the record at the current position. If a 
position is specified (see POSITION) it is acted on before the data is written - so 
the data is written at the new position. Note that with a Keyed File it is an error to 
specify a position which does not exist - the action is abandoned (producing an 
error) without affecting the current position or any temporary lock. 

If neither the file nor the (new) current record are write locked the record is 
temporarily write locked before the data is written - this lock is removed if the 
position changes for any reason, or if it is replaced by an explicit lock. If the lock 
fails the action is abandoned (producing an error), and nothing is written - note 
that any position has already been performed, so the position has changed. 

If a LOCK is specified the required record lock is aquired after the data is written. It 
the record was temporarily locked this lock replaces the temporary one. This may 
be used to unlock the record once it has been updated. Note that no record locks 
are applied if the file itself is read or write locked. 

Note that for Keyed Files PUT can only replace the contents of an existing record 
_ - to create a new record AODREC must be used. _ • • . 
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To replace an existing record, once the new data has been prepared, requires a pair of 
statements of the form: 

POSITION #7 AT replace_ee 
PUT #7. recJ 

where rep 1 a ce_ee gives the number of the record to be replaced and r ec $ contains the new 
data. Note that the previous contents of the record are lost As with PUT there is an elision to 
a single statement of the form : 

PUT #7. rec$ AT replace_ee 

which has the same effect 

(Incidentally, it is also possible to write statements of the foim PUT #7. rec$ NEXT, which 
writes to the record after the current position - but this is less obviously useful.) 

To amend an existing record it is necessary to read it, change as required and then write it 
back to the file. For example: 

GET #7. rec$ AT update_ee 

reel. - ... ’ as required 

PUT #7. rec$ 

where upda te_ee gives the number of the record to be updated. 

Adding a new record is simply a matter of writing to a record which has never been written 
to. The simplest way of doing this is to write to the last record in the file, plus one. For 
example: 

PUT #7. rec$ AT (L0F(#7) \ record_length) + 1 

where record_length gives the record length and rec$ contains the data for the new 
record. (Note that integer division is used here to establish the number of the last complete 
record - so the operation as shown will overwrite any incomplete record at the end of the 
file.) 
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13.3 Keyed files 

Records in keyed files are referred to by quoting the value of a key in a particular index. 
Suppose we had a trivial telephone list, in which the records each contained a name and 
telephone number. To extract a telephone number we would want to use the name to refer to 
the required record. This would be achieved by having an index containing keys whose 
values are the names. 

An index can be visualised as a list of key entries, each entry containing a key value and a 
pointer to the record associated with this key. The keys in this list are always kept in 
alphabetical, or numerical, order - depending on the type of the key. When asked to find a 
record, BASIC 2 Plus takes the given key value and searches for it in the required index. 
Finding the key in the index provides the required pointer to the data record. (Note that 
BASIC 2 Plus maintains its indexes in the form of what is called a B*-tree. It doesn't matter 
what this is. What matters is that this is a very efficient mechanism, so that searching for a 
key in an index is fast, even for very large files.) 

The current position in a keyed file is really a position in an index. The "current record" is the 
one pointed to by the "current index entry". An implication of this is that a record must have 
at least one key in some index. When the last key for a record is deleted the record is deleted 
- since there is no longer an index entry pointing to it, it is inaccessable. 

Each keyed file is actually two files: a Data file and an Index file. The Data file is like a 
random file, holding your information in fixed length records. The Index file is a special file 
that holds all the keys. If either of these files is deleted, the other is useless on its own. 

13.3.1 About keys and indexes 

Each keyed file can have up to twenty different indexes, numbered 1 to 20, all held in the one 
Index file. It is possible, therefore, to arrange to search for data in up to twenty different 
ways. A fairly complicated name and address file might have indexes not only for names but 
also for birthdays, towns, etc. Programs could then be written to extract the names of all 
people with birthdays in the coming week, or all those in a particular town, etc. 

Each index contains keys of a given type. An index has to be defined before it is used. Once 
an index is defined it cannot be re-defined. Defining the index specifies the type of key it will 
contain. Keys may be numeric or string. Numeric keys may only be integers - numeric keys 
with fractional parts are not supported. String keys may be up to 30 characters long, and may 
be fixed or variable length. 
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For some applications it may be sensible to have several key entries in an index with the same 
key value. In an address file with an index of town names this is almost inevitable. In an 
employee file with an index of national insurance numbers it would be most unsuitable. 
When an index is defined it is possible to specify that no two key entries may have the same 
key value. (Note that it is always an error to attempt to have two key entries with a same value 
for the same record - apart from anything else it would be pointless.) 

Where an index does contain more than one key entry with a given key value, the entries are 
arranged in chronological order, with the oldest entry first 

13.3.2 Opening and Closing a Keyed File 

Before you can use a keyed file, you must 'open' it for example: 

OPEN #7 OLD RANDOM "telephon.dat" INDEX "telephon.idx" LENGTH 80 
opens the files TELEPHON.DAT and TELEPHONJDX (which must exist) on stream 7. 

The keyword OLD specifies that the files to be opened must exist Using NEW here would 
specify that the files to be opened must not exist - so a new keyed file is to be created and 
opened. If neither is specified then, if the files exist they will be opened, otherwise they will 
be created and opened When opening existing files they are checked for consistency (see 
below). Creating a keyed file creates an empty file. It is always an error for one of the two 
files to exist and the other not 

When opening an existing keyed file the LE NGTH clause may be omitted; if it is included then 
the length must be the same as that specified when the file was created When creating a 
keyed file the LENGTH clause sets the record length once and for all; if omitted the length is 
set to 128. 

If you want to be sure to create a new keyed file, you should use FI ND* to check if the files 
already exist and KILL to delete them. (Details of FIND) and KILL are given in Chapter IS 
File handling'.) Note that you should do this for both the Data file and the Index file. For 
example: 

IF FINDS(filename*) <> "" THEN KILL filename* 

IF FINDS(indexnameS) <> "" THEN KILL Indexname* 

But beware if you are writing a program for use on a multi-user system, as another user could 
re-create either file (or both) between the KI LL and the OPEN ! 

OPEN sets the current position is "unset" - see "The current position in a keyed file", below. 
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A file stays open until you close the stream. You should not remove a disc containing an open 
file until it has been closed or information may be lost. When you have finished with the 
keyed file, close the stream using CLOSE (as used with all streams, see Chapter 8) for 
example: 

CLOSE #7 

which closes stream 7. 

Closing the stream closes both files. Closing the files writes away any buffered data, updates 
directories and so on. Once the files are closed the stream is released, ready for something to 
be opened on it. 


Consistency check on opening 

Keyed files are relatively complicated structures. If something untoward (such as a power 
failure) happens while the structure is being modified, the result can be an unholy mess. 
Before starting any change to a keyed file BASIC 2 Plus sets markers indicating that the files 
are potentially internally inconsistent These markers are cleared when the file is closed, or 
"consolidated". When an existing keyed file is opened these markers must be clear. 

"Consolidation" is almost equivalent to close followed by open. Keyed files are consolidated 
using the CONSOLI DATE statement, for example: 

CONSOLIDATE #7 

which consolidates the keyed file open of stream 7. 

When opening a keyed file BASIC 2 Plus also performs checks intended to establish that the 
two files it is given were created together as a keyed file. 


f'AKICAl inATC 

CONSOLIDATE 

Us© As soon as a keyed file is changed it is marked "inconsistent". CONSOLIDATE 
causes all outstanding information to be written to the file, and clears the 


"inconsistent marker. 

Syntax CONSOLIDATE [Itjstream-mimber 

' 


If 


#§s 


Description CONSOLIDATE may be applied only to Keyed File streams. 




I 
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13.3.3 Creating Indexes 

Each keyed file can have up to 20 different indexes, numbered 1 to 20. 



You can use as many of these indexes as you like but each index that you use has first to be 
defined. Indexes can be defined as you need them and in any order. When a keyed file is first 
created you will need to define at least one index. 

The statement used to define an index is KEY SPEC, for example: 

KEYSPEC #7 INDEX 1 UNIQUE OFF 

which creates index number 1 in the keyed file open on stream 7. Since no qualifying 
"storage class" is given, the key type is the simplest possible, namely a variable length string. 
The UNIQUE OFF clause specifies that the keys in this index need not be unique, so two, or 
more, keys of the same value are allowed. (String keys are limited to a maximum of 30 bytes/ 
characters.) 

Other examples are: 

KEYSPEC #7 INDEX 12 INTEGER UNIQUE ON 

which creates an index with numeric key values, in this case integers in the range 
-2,147,483,648.. +2,147,483,648, where all keys are to be unique. And: 

KEYSPEC #7 INDEX 6 FIXED 7 

which creates an index with fixed length string key values (length 7). Omitting the UNIQUE 
clause is equivalent to UNIQUE OFF. 

For indexes with numeric keys you can restrict the range of key values. The advantage is that 
this reduces the size of the key value, which makes for a more compact (and hence faster) 
index. This should only be done where you are sure that the key values you will be using will 
never exceed the restricted range - you cannot redefine an index. Using any one of BYTE, 
UBYTE.WORD or UWORD will define a key of smaller range than INTEGER. 
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KEYSPEC 

Use KEYSPEG creates a new index in a Keyed File, and declares the type of key for 
the index. 

Syntax KEYSPEC $]stream-number[,] INDEX index-number [key-spec] [unique] 
where unique is: [,] UNIQUE tnrth-value 

index-number is an integer-expression, giving a vaiue in the range; 1 ..20. 

key-spec is: BYTE, UBYTE, WORD, UWORD or INTEGER 
or: FIXED string-length 

where string-length is an integer-expression, giving a value in the range 1..30. 
unique is: [.] UNIQUE truth-value 

Description KEYSPEC may only be used with Keyed Files. It creates a new index whose key 
values are of the type specified. 

Numeric keys ot five integer types are available, each with its own range of 
allowable values. There is some advantage |n using the smallest range possible - 
because this keeps the key size to a minimum - but once an index exists it 
cannot be redefined. The types, and their allowed ranges are: 

BYTE -128..+127 

UBYTE 0..255 

WORD -32,768..+32,767 

UWORD 0..65.535 

INTEGER -2,147,483,648..+2,147,483,647 

String keys of two types are available, variable and fixed length. If no key-spec is 
given the key type is implicitly a variable length string. If the key-spec is FI XED 
then the key is a fixed length string of the length given. 

If the UNIQUE clause is used and the truth-value gives TRUE, any attempt to add a 
key of the same value as an existing key will be rejected - so all key values in the 
index will be unique. 
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13.3.4 The current position in a Keyed File 


An index is a list of index entries, each containing a key value and a pointer to a record. The 
cmrent position is a pointer to an entry in an index. The current record is the record pointed at 
by the key entry at the current position. So the current position includes: 

the current index - the index most recently selected 

the current index entry - the entry most recently selected in the current index 

the current key value - the key value in the current key entry 

the current record - the record pointed at by the current key entry 


It is possible for the current position not to refer to an entry in an index. The current position 
is "unset" when a keyed file is first opened; it is necessary to select an index to set the current 
position so that it may be used. The current posidon is at "end of index" if an empty index is 
selected, or if the posidon is changed to beyond the last entry in the index - this is analagous 
to being at "end of file". 


The POSITION statement is the most straightforward way of changing the current posidon. 
For keyed files this statement has a number of forms. The simplest sets the current posidon to 
the first entry in a given index, so: 

POSITION #7 INOEX 1 

sets the current posidon in the keyed file open on stream 7 to the beginning of index 1. 

One use of keyed files is as a means of sorting data. Because the keys in an index are always 
held in order you can arrange for your data to be permanendy sorted. To process the data in 
order you simply need something of the form: 

POSITION #7 INDEX 1 
DO UNTIL EOF(#7) 

GET #7. rec$ 

- ' Process the data here 

POSITION #7 NEXT 
LOOP 

which illustrates the use of the P0SITI0N_NEXT statement and the EOF funcdon with keyed 
files. POSITION-NEXT moves the current posidon from the current index entry to the next, so 
steps through the index in order. When POSITION-NEXT steps off the last entry in the index 
the current posidon is set to "end of index”. For keyed files the EOF funcdon returns True 
when the current posidon is "end of index". 
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Another use of keyed files is to look up information using key values as a reference. The 
relevent form of POSITION is POSITION-KEY, for example: 

POSITION #7 KEY "Locomotive Software" 

which attempts to set the the current position to the index entry with the key value 
"Locomotive Software" (in the current index). This is straightforward if there is one, and only 
one, such entry. If there is more than one entry with the required key value, then the position 
is set to the firsL Since equal keys are kept in the indexes in chronological order this is the 
fust such key to have been added to the index. 

POSITION-KEY and POSITION-NEXT can be used together to process all data with a 
particular key value as a reference - POSITION-KEY to find the first relevant record and 
POSITION-NEXT to step through the rest 

When POSITION-KEY is given a key value for which there is no index entry the position is 
set to the first entry with a key value greater than the given key value - or to "end of index" if 
there is no such entry. (To put this another way, the position to just after where the index 
entry for the given key value would be, if only it was there 1) 

The current key value is returned by the functions KEY and KEYS, where the type of the 
function must agree with the type of the current key when it is used. These are more useful 
than you might think, as the following fragment illustrates: 

wants - "Locomotive Software" 

POSITION #7 INDEX 1 
POSITION #7 KEY wants 
DO WHILE KEYS - wants 
GET #7. recS 

_ ' Process the data here 

POSITION #7 NEXT 
LOOP 

which processes all records which are refered to by the key value wants. In this instance the 
test KEYS - wants performs two functions. If there are no records with the required key, 
then the position set by POSITION-KEY cannot have the required key value, so the 00 WHILE 
loop will be skipped. At the end of the 00 WHILE loop the position is advanced. If the new 
position has the required key value the loop is repeated. 

If the current position is "end of index" the functions KEY and KEY S return fake values, where 
these are "larger" than any legal key value. A loop similar to the example above can be used 
to process all records with key values in a given range - even if "end of index" is met 
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Where there is the possibility of equal valued keys in an index the key value alone is not 
sufficient to specify a position. The POSITIONS function returns a string which contains a 
complete description of the cuirent position. For example: 


ps$ - POSITIONS(#7) 

sets the variable psS to a description of the current position in the keyed file open on stream 
7. At some time in the future this string may be used to restore the cuirent position to this 
recorded value, thus: 


E::- 


POSITION #7 AT psS 
The common pair of statements of the form: 



POSITION #7 INDEX 1 
POSITION #7 KEY wants 

may be elided : 

POSITION #7 KEY wants INOEX 1 




13.3.5 Reading records 

Records are read from a keyed file using the statement GET, for example: 



GET #7. recS 

which assigns to the variable recS a copy of the contents of the record at the current position 
in the file open on stream 7. 



The common pair of statements of the form: 

POSITION #7 KEY want 
GET #7. recS 

may be elided into a single statement of the form : 

GET #7. recS KEY want 

which has the same effect unless there is no key entry with the required key value, when this 
will give an error. The POSITION statement tolerates requests to move to non-existant 
positions, as described above, but it is the only statement that does. This is because you have 
the opportunity to check the effect of a POSITION statement before proceeding - which is not 
true of the elided forms. Often the required procedure is of the form : 

POSITION #7 KEY want 
IF KEY(#7> - want THEN 
GET #7. recS 




; 

t= 


END IF 
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Use 

Syntax 

Description 


KEY 

KEY is a function which returns the current key value for a Keyed File. 

KEY ($]stream-number) 

KEY may only be used with Keyed Files. It returns the value of the current key, 
where that is numeric. 

If the current position is "end of index" then KEY returns a value greater than any 
possible numeric key value. 


Use 

Syntax 

Description 


KEYS 

KEYS is a function which returns the current key value for a Keyed File. 

KEY $ ( [tfjstream-number) 

KEYS may only be used with Keyed Files. It returns the value of the current key, 
where that is a string. 

If the current position is "end of index" then KEYS returns a value greater than any 
possible string key value. 


positions 

Use POSITIONS is a function which returns a string which unambiguously specifies 
the current position. 


Syntax 

Description 


POSITIONS (tflstream-number) 

POSITIONS may only be used with Random and Keyed Files. It is most useful 
with Keyed Files. (For Random Files the LOC function returns the current record 
number, which is sufficient). 

In a Keyed File there may be more than one record with the same key value in a 
given index. This means that the key value is not sufficient to re-select a specific 
record. The POSITIONS may be used to get a string which may later be used to 
move back to the current record - so having found a record it is possible to find it 
again. 

Note that the string returned will be usable only while the file remains open. The 
string cannot be saved and used again the next time the file is opened. 
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13.3.6 Updating a keyed file 

You may make any of the following changes to a keyed file: 

• add new indexes 

• add new records 

• add new keys 

• change existing records 

• delete keys 

• change a key 

• delete records 

These changes can be made in any combination, but for simplicity, the following describes 
how to make each type of change separately, in turn. 

Remember that once you start changing a keyed file the Data file and and the Index file stored 
on the disc may be inconsistent The files remain marked inconsistent until the keyed file is 
closed, or until it is consolidated. Files which are marked inconsistent cannot be opened. It is 
good policy to make regular copies of your valuable data - lest a power failure or other 
accident destroy it. 

Adding new indexes 

The statement KEY SPEC creates a new index. See "Creating Indexes" above. 

Adding new records 

Records are added using AODREC, not PUT (PUT is used to change existing records.) All 
records in a keyed file must have at least one key, so AOOREC takes both the data for the new 
record and its first key value. For example: 

ADOREC W. rec$ KEY first INDEX 5 

which writes the value of recJ to a new record in the file open on stream 7, and adds a new 
index entry to index S. The new index entry will have the key value f i rst (the index must, 
naturally, have numeric keys) and will point at the new record. If the INDEX clause were 
omitted the current index would be assumed. 

Note that ADDREC also sets the current position to the new index entry, so the new record 
becomes the current record. 

If the new record is to have more than one key, the further keys may be added using ADDKEY, 
as described next. 
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ADDREC 

Use ADDREC adds a new record to a Keyed File. 

Syntax ADDREC [JHstream-number, string-expression [,] key [[,] LOCK lock-type] 
where key is: KEY key-value ([,] INDEX: index-number] 

where key-value is an expression, giving a value compatible with the index’s key type 
index-number is an integer-expression, giving a value in the range 1..20. 

Description ADDREC may only be used with Keyed Files. It creates a new record with a key of 
the given value, in the given index (or in the current index, if no index is 
specified). The position is changed to the new record. 

If the file is not write locked the new record is temporarily write locked before the 
data is written - this lock is removed if the position changes for any reason, and if 
it is replaced by an explicit lock. 

If the index was specified to reject two keys of the same value (see KEY SPEC) 
then any attempt to add a key of the same value as an existing key will result in 
an error. Where keys of the same value are allowed, they are placed in the index 
in time order, oldest first. 

' 

The data given by the string-expression is written to the file. If there are fewer bytes 
of data than the record will hold the data is padded on the right with zeros. It is an 
error to attempt to write more than the record will hold. 

In the event of an error the action is abandoned without affecting the current 
position or any temporary lock. 

If a LO C K is specified the required record lock is aquired after the record is 
created, replacing the temporary one. This may be used to unlock the record after 
its creation. Note that no record locks are applied if the file itself is read or write 
locked. 
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Adding new keys 


A record may have as many keys in as many indexes as you wish. It may even have more than 
one key in the same index (provided all keys in the same index have different values). 

The statement ADDKEY adds a new key for the current record. So: 

ADDKEY #7 KEY extra_keyS INOEX 8 

adds a new index entry to index 8 in the file open on stream 7. The new index entry will have 
the key value extra_key$ (the index must, naturally, have string keys) and will point at the 
current record. If the INDEX clause were omitted the current index would be assumed. 

ADOKE Y does not affect the current position. 

Changing an existing record 

The statement PUT will replace the contents of a record, for example: 

PUT #7. recS 

which writes the value recS to the record at the current position in the file open on stream 7, 
replacing the existing contents of the record. 

To change part of a record, you need first to GET the current contents. The changes can then 
be made and the new version of the record written back. To change a telephone number in a 
trivial telephone book keyed file would need something of the form: 

RECORD tel; nameS FIXED 30. number 
want! - "Locomotive Software” 
new_num - 885529 
POSITION #7 KEY wants INDEX 1 
IF KEYS(#7) - wants THEN 
GET #7. recS 

recS.tel.number - new_num 
PUT #7, recS 
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ADDKEY 

ADDKEY adds a new key for the current record. 

ADDKEY [^stream-number],] new-key [[,} LOCK lock-type] 

new-key is: KEY key-value {[,] INDEX index-number] 

key-value is an expression ,giving a value compatible with the index's key type 

index-number is an integer-expression, giving a value in the range 1 ..20. 

ADDKEY may only be used with Keyed Files. It creates a new key for the current 
record of the given value, in the given index (or in the current index, if no index is 
specified). The position is unchanged. 

If neither the file nor the (new) current record are write locked the record is 
temporarily write locked before the key is added - this lock is removed if the 
position changes for any reason, and if it is replaced by an explicit lock. If the lock 
fails the action is abandoned (producing an error), and nothing is added. 

II a LOCK is specified the required record lock is aquired after the key is added. If 
the record was temporarily locked this lock replaces the temporary one. This may 
be used to unlock the record after the update. Note that no record locks are 
applied if the file itself is read or write locked. 

If the index was specified to reject two keys of the same value (see KEY SPEC) 
then any attempt to add a key of the same value as an existing key will result in 
an error. In any case attempting to add a key of the same value as an existing key 
for the current record will result in an error.: Where keys of the same value are 
allowed, they are placed in the index in time order, oldest first. 

Note that ADDKEY can only add keys for an existing record - to create a new 
record ADDREC must be used. 
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Deleting keys 


The statement DELKEY will delete keys. There are two foims of DELKEY, the first will delete a 
key for the current record, thus: 

DELKEY #7 KEY dead.keyS INDEX some_index 

which deletes the index entry with the key value dead_key$ in the index some_i ndex in the 
file open on stream 7, provided there is such an entry pointing at the current record. If the 
INDEX clause were omitted the current index would be assumed. 

The second form of DELKEY deletes thekey entry given by a POSITIONS string, thus: 

psS - P0SITI0NS(#7) 

. * etc. etc. etc. 

DELKEY #7 AT psS 

stores the then current position in the string p s S which is later used to delete that index entry. 

DELKEY does not change the current position, unless the index entry deleted is the current 
position (!), in which case the current position moves to the next index entry (as if 
POSITION-NEXT had been executed before the current index entry was removed). 

If the key that is deleted is the only one for that record, the record will also be deleted. 


Changing a key 

There is no direct mechanism for changing a key, but a combination of ADDKEY and DELKEY 
will do the job. 

To change a name in a trivial telephone book keyed file would need something of the form: 

RECORD tel: nameS FIXED 30. number 
wasS - "Mary Delaney" 

1s_nowS - "Mary Kaplan" 

GET #7. recS KEY wasS INDEX 1 
recS.tel.names - 1s_nowS 
PUT #7. recS 
ADDKEY #7 KEY 1s_nowS 
DELKEY #7 KEY wasS 

It is not strictly necessary for the key value to also be recorded in the record, but it is tidy. 
Note that the GET would fail if there wasn't an index entry for Mary Delaney. The actual work 
of changing the key value is done by the last two statements in this example. Note that doing 
add followed by delete ensures that the record is not deleted by mistake! 
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DELKEY 


Use 


Syntax 

where 


DELKEY deletes a key for the current record. 

DELKEY [f]]stream-numberf,] key [[,] LOCK lock-type] 

key is: KEY key-value J.] INDEX index-number] 
or: AT position-string 

where key-value is an expression, giving a value compatible with the index's key type 
index-number is an integer-expression, giving a value in the range 1 ..20. 
position-string is a string-expression, giving a value once returned by POSITIONS. 

Description DELKEY may only be used with Keyed Files. 

DELKEY-KEY deletes the given key, in the given index (or in the current index, if 
no index is specified), for the current record. If neither the file nor the current 
record are write locked the record is temporarily write locked before the key is 
deleted - this lock is removed if the position changes for any reason, and if it is 
replaced by an explicit lock. If the lock fails the action is abandoned (producing an 
error), and nothing is deleted. 

DELKEY-AT deletes the given key. If neitherthe file nor the current record are 
write locked the record is temporarily write locked before the key is deleted- this 
lock is then removed. If the lock fails the action is abandoned (producing an 
error), and nothing is deleted. 

If the key deleted was the current key the position changes as if POSITION-NEXT 
had been executed. If this is the last key for the current record the record is also 
deleted. 

If a LOCK is specified the required record lock is aquired after the key is deleted. If 
the record was temporarily locked this lock replaces the temporary one. This may 
be used to unlock the record after the update. If no lock is specified the (new) 
current record is temporarily write locked - this lock is removed if the position 
changes for any reason, and if it is replaced by an explicit lock. Note that no 
record locks are applied if the file itself is read or write locked. 
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At the end of the example the current position would be the index entry following where the 
old key value was - since the DELKEY deletes the then current position. This effect can be 
avoided by using the REPOSITION statement, thus: 

ADOKEY #7 KEY is_now* 

REPOSITION #7 KEY is_now* 

OELKEY #7 KEY was* 

which performs the change of key as before, but leaves the current position set to the new key " 
for the record. REPOSITION similar to POSITI ON, but will only change the current position if 
it can do so without changing the current record. This, is of vital importance if there is the 
possibility of two index entries with the same key value. If there was already a Mary Kaplan 
in the index, using plain POS ITION would delete the wrong index entry! 

Deleting a record 

To delete a record, you must delete each of its keys, using DELKEY as described above. When 
the last key for a record is deleted the record is automatically deleted. 


13.3.6 The construction and use of keys 


Using the shortest key values possible can be advantageous but remember - once an index is - 
defined it can't be changed, so be sure the key type you choose will cope with all future needs. - 


Where a key is naturally an integer, or can readily be turned into one, then you should use a 
numeric key. (Note: BASIC's numeric form of the date fits nicely into a UWORD type key.) 

Where a key is naturally a string of varying length - for example a name - then you should 
use a variable length suing key. Fixed length suing keys are useful only where the key values 
really are all the same length, or very nearly so. 


Suing keys are sorted by simple comparison of the string values - just like comparing two 
strings in an expression (see Chapter 4). Before using a suing as a key it may be worthwhile 
converting it to upper or lower case and removing leading and trailing spaces. If the order 
implied by the values used to represent characters in strings is not acceptable you will need to 
transform the suing. 

It is also possible to construct and use composite keys. Suppose you wish to have an index for 
finding records firstly by town and secondly by date - so that, for example, you can find all 
records which contain information about events in Dorking on the 25th of October. For this 
sort of application a composite key is required. The recommended way of achieving this is 
illustrated by: 

RECORD composItejcey; name* FIXED 20. date_of_event UWORD KEY 
key_value*.composite_key.name* - "DORKING” 
key_value*.composite_key.date_of_event - DATE("25/10/52") 














REPOSITION 

Use REPOSITION moves to a new position in a Keyed file, without changing record. 

Syntax REPOSITION (#]stream-number [,] key ([.} LOCK lock-type) 

where key is: KEY key-value R,] INDEX index-number] 

where key-value is an expression, giving a value compatible with the index's key 
[ypeindex-number is an integer-expression, giving a value in the range 1. .20. 

Description REPOS ITION may only be used with Keyed Files. It changes the current position 
to the given key value in the given index (or the current index if is none is given) 
WITHOUT moving to a new record. The key specified must, therefore, exist for 
the current record. 

Once positioned any record lock specified is applied. If the lock fails an error is 
raised, but the new position has been set. Note that no record locks are applied if 

__ the file itself is read or write locked. _ v :: 

This uses a RECORD structure to construct the composite key_val ue$. Note the use of the 
qualifier KEY in the RECORD definition - this ensures that the number is held in such a way 
that the resulting string is effective as a string key value. 

For use in the construction of keys BASIC 2 Plus provides the function UNIQUE. UNIQUE 
returns an integer, which is 0 the first time it is used for a given file, 1 the next time, and so 
on. The maximum result that will be produced is 2,147,483,647 - which means that you can 
exhaust this supply of numbers by using one every 10th of a second, day in day out, for a little 
under seven years._ 

UNIQUE 

Use UNIQUE is a function which returns the next "unique" number for a Keyed File. 
Syntax UNIQUE (f))]stream-rrumber) 

Description UNIQUE may only be used with Keyed Files. It returns an integer in the range 
0..2,147,483,647. 

When constructing a new key it may be useful to include a value which ensures 
that the key is unique. In a Keyed File a number is kept. This number is set to 
zero when the file is created. The UNIQUE function returns the current value of 
that number, and increases it by one, for the next time. Note that the value is not 
only unique, but also implies a time ordering. 

(Incidentally, if one of these "unique" numbers were used every tenth of a second 
_they would be exhausted in a little under seven years continuous use!) _ 
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UNIQUE may be used to construct composite keys which are guaranteed to be unique, and 
which will sort in chronological order. 

UNIQUE may also be used to link keyed files together. Suppose you have a keyed file of 
components used in a factory. One of the pieces of information you might wish to keep is the 
name and address of the supplier of each component If there are a large number of 
components and a small number of suppliers it would be very wasteful to duplicate the 
supplier information in each component record. So you might use a second keyed file, 
containing just the information about the suppliers. How then to refer from the components 
file to the suppliers file ? Answer by using a UNIQUE value as a "link". The suppliers file 
requires an index of these "link"s. Each time a new supplier is added to the suppliers file the 
next UNIQUE value is allocated to it, and a "link" key added to the index. Each record in the 
components file can now contain the "link" value for its supplier. So to find the supplier for a 
given component it is only necessary to take the "link" value form the component record and 
look in (he suppliers file "link"s index to find the relevant supplier record. 


13.4 File & Record Locking on Multi-user systems 

All versions of BASIC 2 Plus are multi-user. This means that when BASIC 2 Plus runs under 
a multi-user operating system, it is possible for different users to access the same files. In 
particular, it means that a number of people can use the same database at the same time. 

Multi-user systems provide a way of sharing resources, including data files. 

However, sharing tiles can produce problems when files are being altered. This is because 
while you are making the changes, the data in the file may be inconsistent - and if the tile is 
read at this stage by another user, incorrect information might be read. 

This is most often the case with keyed access files, where the index file is updated separately 
from the data file, but it can happen with any type of tile. Some control is therefore needed to 
ensure that all users are all presented with consistent data. This is straightforward if they are 
only reading the file, but more complicated if the tile is being changed. 

This control is provided by 'locking' the areas of change until the modification has been 
completed, when the areas may be released. The locking prevents all other users accessing 
areas which are changing, where they would otherwise be in danger of accessing incomplete 
or inconsistent information. 

Locking requests are ignored when BASIC 2 Plus is run on single-user system. Thus 
programs that have been designed for use in a multi-user environment will work without 
modification on a single-user system. 
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13.4.1 Locking 


There are two levels of locking. File and Record, and three lock states - unlocked, read- 
locked and write-locked. The precise effect of the different types of lock depends on the 
circumstances under which the lock is applied but, in general terms: 

• unlocked means that the file/record can be read or written by any user 

• read-locked means that the file/record can only be read by any user, and 

• write-locked means that the file/record can be read or written but only by the user that 
applied the lock 

File locking applies to the whole of the file, ie. to every record in the file. It can be applied to 
any file, sequential, random or keyed. Record locking applies to individual records. It can be 
applied to individual records in random and keyed files, but not at all to sequential files. 

In general, locks are requested explicitly by using the parameter LOCK lock in the appropriate 
file handling operation. Some operations also temporarily write-lock the record they are 
processing. 

13.4.2 File locking 

A file lock is specified by including LOCK lock in the relevant OPEN statement. The lock can 
then only be changed by closing and opening the file again. 

The locks which can be applied are: 
lock Lock name 

0 Unlocked 

1 Read-locked 

2 Write-locked 

If a lock is not specified, the file will be opened write-locked, except for sequential files 
opened for IN PUT. which are opened read-locked by default. 

If a file is opened by more than one user at once, they must all open it with the same lock. If 
a user opens a file with a write lock, no other user can open the file at all until the lock is 
removed. 
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The cuirent file lock affects what can be done with the file by all users, as follows: 

• an unlocked file can be read or written by any user, subject to any record locks 

• a read-locked file can only be read, by any user 

• a write-locked file can be read or written by the user who opened it, but the write-locking 
prevents any other userfrom opening the file. 

The file lock applied by a user is released when that user closes the file. 




13.4.3 Record locking 

Records in random or keyed files can be unlocked, read-locked or write-locked, in a similar 
way to files (but see the note about DOS implementations below). 

Record locking is only needed where a file has been opened unlocked. A write-locked file has 
all of its records implicitly write-locked. A read-locked file has all of its records implicitly 
read-locked. Records are locked either by specifying a lock in the statement used to access 
them, or in an explicit LOCK statement 




A record's lock state is determined by the highest lock successfully applied to it The locks 
which can be attempted are: 

Limitation 


lock 

0 

1 

2 


Lock name 
unlocked 
read-locked 
write-locked 


none 

fails if record write-locked 

fails if any other user has locked the record 


w 


The three states allow different operations on the record, as follows: 
• unlocked records can be read or written by any user. 


• read-locked records and their keys can only be read, not deleted nor changed (nor can 
you add keys for a read-locked record) 

• write-locked records and their keys can be read or written, but only by the user who 
write-locked them 

To obtain or release a permanent lock, use the LOCK statement or append the optional LOC K 
lock to statements that process the record, for example: 

POSITION #7 KEY want* LOCK 1 

which changes the current position and read-locks the then current record. That record can 
then be read in the sure knowledge that its contents cannot be changed "under your feet”. 
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Later you may wish to change the record, so a write-lock must be aquired, thus: 

LOCK #7. 2 

the new value of the record can now be written. If the transaction is over, so the record is no 
longer required to be locked, un-lock it thus: 

LOCK in. 0 

In fact the PUT and the LOCK can be elided: 

PUT H7. rec$ LOCK 0 

Where a lock is specified in a GET, PUT.AODREC.ADDKEY or DELKEY the lock is aquired after 
the operation has finished. 

A lock can only be released by the user that applied it, either by explicidy specifying a lock of 
0 or by closing the file. 

No more than 20 locks can be applied to one file at once. 


LOCK 

Use LOCK sets a new record lock. 

Syntax LOCK [ft]stream-number , lock-type [[.] position] 

LOCK $}stream-number (Imposition] (,] LOCK lock-type 

where position is as described in POSITION. 

Description LOCK may only be used with Random and Keyed Files. It sets the given lock at 
the given position - or at the current position if none is given. The position is not 
changed. For Keyed Files any position specified must exist. Note that no record 
locks are applied if the file itself is read or write locked. 

If a position is specified then it means : 

NEXT the record following the current. 

AT record-number the record specified - Random Files only. 

AT position-string the record specified. 

KEY key-value ([.} INDEX index-number] 

the first record with the given key value in the given 
index (or the current index if is none is given) 

- Keyed Files only. 

INDEX index-number the first record in the given index - Keyed Files only. 
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Temporary Record Locks 

A temporary lock is a write-lock which BASIC 2 Plus aquires, in the absence of any other 
lock, whenever a user executes any of the statements: POSITION, GET, PUT, ADDREC.ADDKEY 
andOELKEY. 

BASIC 2 Plus only maintains one temporary lock on each stream, and that lock applies only 
to the current record. So the temporary lock on a record is released as soon as a different 
record becomes the current record. 

The temporary lock mechanism is adequate for simple programs where only one record at a 
time is involved in any transaction. Where more than one record is involved the program 
must maintain its own "explicit" locks. 

If a lock is specified inaPOSITION statement there is no need to aquire the temporary lock as 
well. For GET, PUT, ADDREC, AODKEY and DELKEY operations the temporary lock is aquired 
unless the record is already locked; once the operation has finished any explicit lock replaces 
all previous locks for the record (including any temporary lock). 

DOS implementations 

DOS does not support full read- and write- locking of records, so in implementations of 
BASIC 2 Plus which run under DOS, record locks may not work exactly as specified above. 

All locks, both read and write, are implemented as 'advisory locks'. An advisory lock may 
have the effect of a write lock (that is, only the user who applies the lock may access the 
record). However, an advisory lock will prevent any other user from locking the record. The 
effect of this as far as you, a user of BASIC 2 Plus, are concerned is that all record read-locks 
are treated as write-locks. 

BASIC 2 Plus limits the number of record locks which can be applied to any one file to 20. 
DOS limits the number of record locks which can be applied over the whole system. (The 
default limit is 20.) 
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13.4.4 Strategy in writing multi-user programs 

The main recommendation is that you should always open files with the lowest level of 
locking that your program needs. 

Random and keyed files are opened write-locked by default. If a program is just going to read 
a file, it should open it read-locked - so that other users may also read the file. Even if it is 
going to change the file, it would be friendlier to open the file unlocked and lock records that 
it wants to read or change - though write-locking the file does have the advantage of 
simplicity. 

Sequential files are, by default, opened read-locked (INPUT) or write-locked (OUTPUT. 
APPEND). These default locks are suitable for most processing. 

Once the file is open, you should aim to minimise the time that any record is kept locked 
(because otherwise you may stop other users from working). 

You also need to bear in mind that different users may be doing the same task at almost the 
same time. For example, if your strategy for acquiring the next invoice number is to find out 
the invoice number of the last record and add one to it, it is possible that a second user may 
acquire the same number by this technique between the time that the first user acquired the 
number and added the new invoice to the data base - particularly if the new number is sought 
before any of the other invoice information is entered. In such a case, it would be better to 
leave finding out the new invoice number until immediately before the new record is written. 
(Using a lock to prevent conflict here is not a good scheme because it is likely to stop others 
from working.) 

By following the guidelines here, you should be able to produce programs that will work 
efficiently on single-user systems and multi-user systems. If you do not follow these 
guidelines, your programs will still work on multi-user systems, but will not allow other users 
to share files while you are using them. 
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This chapter explains about the various commands which BASIC 2 Plus uses to control the 
computer's screen. 

It gives the commands to: 
manipulate windows directly from your program 
determine the size and position of a window on the screen 
change the title and information line in a window 
change the form of the cursor and the mouse pointer 
find the position of the cursor and the pointer 
allow the user to make selections using the mouse 
incorporate Alert boxes into a program 




14.1 Window visibility 

The visibility of a window is controlled using the commands WINDOW OPEN and WINDOW 
CLOSE. 

WINDOW CLOSE removes a window from the display but preserves its contents (ie. its virtual 
screen): 

WINDOW [tfstream-number] CLOSE 

while WINDOW OPEN makes it visible again, with all its contents intact, in its last defined 
position: 

WINDOW [ifstream-number] OPEN 



This also makes this window the top window, that is, it places it 'in front of any overlapping 
window on the display. 



Note the difference between closing a stream (which loses all the information displayed in a 
virtual screen) and closing a window (which simply makes it invisible). 
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WINDOW 

Use WINDOW statements change the size, position etc. of Screen Windows. 

Syntax WlHOO\t(ifstream-number] CLOSE 

or WINDOW $stream-number] FULL truth-value 

or WINDOW [if stream-number] OPEN 

or WINDOW fltstream-number] SIZE width, height 

or WINDOW [ifstream-number] PLACE point 

or WINDOW [ifstream-number] TITLE string-expression 

or WINDOW [Ifstream-number] INFORMATION string-expression 

or WINDOW [ifstream-number] MOUSE mouse-form 

or WINDOW [ifstream-number] CURSOR truth-value 

or WINDOW [ifstream-number] SCROLL point 

where mouse-form is an integer-expression, giving a value 
point is x-position[; y-position] or; y-position 

where x-position, y-position are integer-expressions, giving a value in the range 1 ..5000 
width and height are integer-expressions, giving a value in the range 1 ..5000 

Description WINDOW-CLOSE closes the window, in the same way that clicking on its close 

box. WINDOW-OPEN brings the window back onto the screen, if it has been closed, 
and, in any case, makes it the top window. WINDOW-FULL sets the window to the 
largest possible size if the truth-value is TRUE, otherwise sets it to the last size 
specified (explicitly). WINDOW-SIZE sets the size of the window, the width and 
height give the size in screen pixels for Graphics Windows and in characters and 
lines for Text Windows. WINDOW-PLACE sets the position of the bottom left hand 
comer of the window on the actual screen, the x-position and y-position give the 
position in screen pixels - if either is omitted the position in that dimension is 
unchanged. 

WINDOW-TITLE and WINDOW-INFORMATION set the window title and window 
information lines to the given string. Note that these are limited to 80 characters - 
any excess characters are discarded. Setting the window information line has no 
effect if the information line was not enabled in the SCREEN statement. 

WINDOW-MOUSE sets the form of mouse to be shown when the mouse pointer is 
in the window and the window is the top window. See ??? for a description of the 
possible forms. 
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WINDOW-CURSOR sets whether to display the cursor or not - if the truth-value is 



.SCROLL sets the position of the bottom left hand comer of the window 
on the virtual screen, the x-position and y-position give the position in user 
coordinates - if either is omitted the position in that dimension is unchanged. 

CLOSE WINDOW 


Use CLOSE 
Syntax CLOSE WINDOW 


window-number 



Description CLOSE WINDOW performs the same function as WINDOW-CLOSE, but without 
requiring the window to be opened on a stream. This may be used to remove 
unwanted windows from the screen with the minimum of effort. 

' \ ;I • I 1 ' " • . iillii 1 - \ 
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You can also remove a window from the display by using its window number with the C LOSE 
WINDOW command: 

CLOSE WINDOW window-number 







This command is mainly intended for removing the Edit (window number 3) or Dialogue 
(window number 4) windows from the display. (You cannot use WINDOW CLOSE for this, 
since these windows are not attached to streams.) 


14.2 Window size and position 

To change a window's size, use the command WINDOW SIZE: 

WINDOW [ft stream-number] SIZE width, height 

width and height art integer-expressions specifying the new dimensions in pixels. These will be 
rounded up to satisfy any UNIT constraint and are subject to any limits imposed by MAX IHUH 
and MINI MUM in the virtual screen definition. (See Chapter 9.) 
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To make a window full size, use: 

WINDOW [^stream-number] FULL ON 

This displays the window as large as is allowed by the display (subject to any maximum 
speciGed using SCREEN). To restore the window to its previous size, use: 

WINDOW Mstream-number] FULL OFF 

To change the position of a window on the display, use the command WINDOW P LAC E: 
WINDOW Wstream-number ] PLACE x-.y 

where x and y (in pixels) specify the new position on the display of the bottom left comer of 
the window from the bottom lefthand comer of the display. 

Note that these commands don’t automatically move the window to the top. If you need to 
make the window the top one, use: 

WINDOW [ # stream-number] OPEN 

Querying the size and position of a window 

The information you can obtain about a window includes: 

• the size of the window, both with and without title lines and scroll bars 

• the width of the scroll bars 

• the position of the window on the display, and 

• the position of the window on the virtual screen (ie. its scroll position) 

To determine the current size of a window (in pixels), use the following functions: 

result - X WIN DOW/X Ustream-number)] 
result - YWINDOW/( IIstream-number)] 

where result gives the size of the usable portion of the window, ie. the part that displays the 
contents of the virtual screen. 

or result- XACTUAL[(trstream-number)] 
result - YACTUAL/X rtstream-number)] 

where result gives the overall size of the window, including its scroll bars, title and 
information line. 
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XWINDOW & YWINDOW 

Use 

The XWINDOW, YWI NDOW functions return the size of a window in device pixels. 

Syntax 

XWIN DOW midstream-number) ] 

YWIND0W(( [jfjstream-number)) 

Description 

XW INDOW returns the width of the Window, YWI NDOW returns the height. These 
values are in screen pixels and give the width and height of the inside of the 
window - that is that part in which the virtual screen is shown - excluding title, 
scroll bars and all other "border. 


XACTUAL & YACTUAL 

Use 

The XACTUAL, YACTUAL functions return the actual size of a window in device 
pixels. 

Syntax 

X ACTU A L[( Upstream-number)] 

Y ACTU A l[([#]stream-number) ] 

Description 

XACTUAL returns the width of the Window, YACTUAL returns the height. These 
values are in screen pixels and give the width and height of the complete window 
- including title, scroll bars and all other "border. 
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To determine the size of a window's scroll bars and title line, use the following functions: 

result - X BARA ftstream-numbe/)] 
where result is the width (in pixels) of the vertical scroll bar 
result- YBAR/X ftstream-number)] 
where result is the height (in pixels) of the horizontal scroll bar 

To determine the current position of a window on the display, use the functions X P LAC E and 
YPLACE: 

result - X P LAC E/X IIstream-number)} 
result - Y P LAC E/X ftstream-number)] 

The results give the position of the bottom left comer of the window, in pixels. 



XBAR&YBAR 

Use 

XBAR and YBAR are functions which return the actual size of the scroll bars of a 
window in device pixels. 

Syntax 

XBAR/( (ft]stream-number) ] 

YBAR [((ftjstream-number)] 

Description 

XBAR returns the width of the right hand window "border, YBAR returns the height 
of the bottom window "border. These values are in screen pixels. (The right hand 
window "border is the vertical scroll bar and the bottom window "border" is the 
horizontal scroll bar - hence the names.) 


Note that XACTUAL - XWINDOW - XBAR gives the width of the left hand window 
"border. There is a similar construction for the top window "border. 


XPLACE & YPLACE 

Use 

XPLACE and YPLACE are functions which return the position of the bottom left 
hand corner of a window in device pixels. 

Syntax 

X P LAC E[( (ftjstream-number ) ] 

Y P LAC E/X (ftjstream-number)] 

Description 

XPLACE and YPLACE give the screen coordinates of the bottom left-hand corner , 
of a window. These values are in screen pixels. 
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14.3 Scrolling 

When text is output to a window and there is no cursor in the window (the default case), you 
only see text that is written to the area of the virtual screen that is shown in the window. If the 
cursor is turned on, the window automatically scrolls to keep the text being output in view. 

Text which has been output to the screen but which isn't shown in the window can usually be 
brought back into view by scrolling the window, using the mouse or BASIC commands. 
(Text will, however, be lost if the amount of text on the screen exceeds ((how much)).) 

To scroll a window from within a program, use the command WINDOW SCROLL: 

WINDOW [ftstream-number] SCROLL x:y 

This makes point x;y the bottom left point in the window, x and y specify user coordinates on 
a graphics screen, and text coordinates on a text screen 

Scrolling moves a window over its virtual screen and a window can only be scrolled in 
directions in which there is more of its virtual screen to reveal. As a result, BASIC 2 Plus may 
modify the scroll position appropriately. 

It is the size of the virtual screen (as defined in the relevant SCREEN command) which 
determines whether scrolling can occur and if so, how far it can go. For example, if a screen's 
width were defined as FIXED, you could not scroll its window horizontally - in fact, you 
could see that this was the case, because it would be displayed without a horizontal scroll bar. 

To determine the current position of a window in its virtual screen, use the functions 
XSCROLL and YSCROLL: 

result = XSCROLL/X It stream-number)] 
result= YSCROLL [(ft stream-number)] 

These return the position of the bottom left comer of the window, in user coordinates on a 
graphics screen, and text coordinates on a text screen. 
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XSCROLL & YSCROLL 

Use XSCROLL and YSCROLL are functions which return the position of the window on 
the virtual screen in user coordinates. 

Syntax X S C RO L l[([ti]stream-number) ] 

Y SC RO LLf( HHstream-number)] 

Description These functions return the position on the virtual screen of the bottom left corner 
of the window. These values are in user coordinates for Graphics Screens, or 
characters and lines for Text Screens. 
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14.4 Window legends 

Each window has a title, shown in the window's title bar. A special piece of text can also be 
displayed on the line immediately below the title bar - the 'Information line’ - if this line was 
specified when the virtual screen was defined (see Section 9.1 'Redefining virtual screens'). 

To change the title of a window (as displayed in its title bar), use: 

WINDOW [Vstream-numberJ TITLE string-expression 

To change the information line of a window, use: 

WINDOW [fstream-number ./ INFORMATION string-expression 

The string expressions you use for the title and the information string are not restricted in any 
way. In particular, you don’t have to make them less than some specified length: if the title or 
the information string are longer than the space available for them, BASIC 2 Plus simply 
doesn't display any more characters than there is room for. 


14.5 The cursor and the pointer 

BASIC 2 Plus commands are also available to: 

• specify whether the cursor is displayed in the window 

• move the cursor around the window 

• define the shape of the cursor, and 

• define the shape of the mouse pointer 

14.5.1 Specifying whether the cursor is displayed 

The cursor is turned off, by default. 

To specify whether the cursor is visible or not, the command to use is 
WINDOW [ iistream-number ] CURSOR truth-value 

If truth-value is true, the cursor is made visible; if truth-value is false, it is made invisible. 
This also affects how the window scrolls, in that when the cursor is visible, scrolling 
automatically keeps the cursor in the window. When the cursor is invisible, graphics and text 
may be drawn outside the visible area. 
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LOCATE 

Use LOCATE moves the cursor to a given character and line position. 

Syntax LOCATE [Itstream-numberJ column;line 
Description The cursor is moved to the given position, column and line are text coordinates. 

MOVE 

Use MOVE moves the cursor to a;given position. 

Syntax MOVE [Itstream-number.] xcoordiycoord 

Description The cursor is moved to the given position, xcoord and ycoord are user coordinates. 

14.5.2 Moving the cursor round the window 

The cursor can be moved round a window by using the commands LOCATE and MOVE. 

LOCATE [Itstream-numberJ x;y 
MOVE [Itstream-number.] x:y 

LOCATE moves the cursor to a position given in text coordinates (columns and lines); MOVE 
moves it to a position given in user coordinates. LOCATE can be used on either a text screen or 
a graphics screen; MOVE can only be used on a graphics screen. 

Neither of these commands can be used to move the cursor to a position off the virtual screen. 

14.5.3 Defining the shape of the cursor 

A cursor on a text screen is always a solid oblong, but a cursor displayed on a graphics screen 
can take any of three different forms, in keeping with its potential use for graphics, text and 
turtle graphics. 

To change the cursor appearance on a graphics screen, use: 

GRAPHICS [Itstream-number] CURSOR style 
where style is an integer-expression in the range 1 to 3: 

1 produces a cross hair -f- 

2 produces a text cursor: |_ 

3 produces a 'turtle': Q-V 
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14.5.4 Defining the shape of the mouse pointer 

The appearance of the mouse pointer can also be changed, using: 

WINDOW fflstream-number] MOUSE mouse-form 

where mouse-form is an integer-expression specifying the form the mouse pointer should take 
while it is in that stream's window and that window is the top window. 


14.5.5 The Mouse 

To make sense of selections that the user makes on the screen, you need to be able to tell what 
the current position of the pointer is and whether the mouse button has been clicked. (You 
need to wait for a button to be clicked to be certain that the pointer is in its final position.) 

To read the current mouse pointer position, use the functions XMOUSE and YMOUSE: 

XMOUSE 

YMOUSE 

These give the X and Y position of the mouse pointer, in pixel co-ordinates. 

To read the mouse buttons, use the function BUTTON: 

BUTTONn button)! 

button is an integer-expression in the range 1 -16. It specifies which button to read, numbering 
the leftmost button as 1, the next as 2, and so on (depending on the number of buttons on the 
mouse). If no argument is specified, the leftmost button is read. So if the mouse on your 
system has just one button, you can simply use BUTTON. 

BUTTON returns an integer in the range -1 to +15. -1 means that the button is not being 
pressed. Other results indicate that the button is being pressed and show whether any keys are 
being pressed at the same time. Each bit of the result indicates the state of a different key, as 
follows: 

Bit Significance 

0 righthand □□ 

1 lefthand m 

2 I Ctrl ) 

3 fTTI 
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For example, a result of 5 (&X0101) indicates that the mouse button, GsD and righthand G£] 
are all being pressed, while a result of 0 means that no extra keys were held down when the 
button was clicked. 
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XMOUSE & YMOUSE 

Use The XMOUSE, YMOUSE functions return the current position of the mouse pointer in 
device pixels. 

Syntax XMOUSE 
YMOUSE 

Description These functions return the physical screen coordinates of the mouse pointer. 

XMOUSE returns the distance in screen pixels from the left hand edge of the 
screen to the "hot spot" of the mouse pointer, 0 means the mouse is at the 
extreme right hand edge. YMOUSE returns the distance in screen pixels from the 
top of the screen to the "hot spot" of the mouse pointer, 0 means the mouse is at 
the very top. 

BUTTON 

Use BUTTON is a function which returns the state of the mouse button. 

Syntax BUTTON [(button-number)] 

where button-number is an integer-expression, giving a value in the range 1 ..15. 

Description If a button-number is given it specifies which mouse button is to be tested, otherwise 
button 1 is assumed. If the mouse has but one button it is button number 1. If the 
mouse has more than one button they are numbered from 1 from left to right. 

BUTTON returns a value which indicates whether the mouse button is currently 
being pressed, and if so what "shift" keys are being pressed at the same time. A 
return value of -1 indicates that the button is not being pressed. Any combination 
of zero and the following values indicates that the button is being pressed: 

&X0001 - the right hand shift key is being pressed 

&X0010 - the left hand shift key is being pressed 

&X0100 - the Ctrl key is being pressed 

&X1000 - the Alt key is being pressed 
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14.6 Using an Alert 

An Alert box consists of an optional standard icon (Note, Wait or Stop), up to five lines of text 
and up to three exit buttons. Onee exit button, the default, can be shown with a thick border, 
and in that case pressing the return key is equivalent to clicking on the highlighted button. 

To generate an Alert box, use the ALERT statement This defines the box and displays it. 
The user can then click on one of the exit buttons to enable the program to continue. The 
syntax is: 

ALERT icon-number TEXT texl-specs BUTTON button-specs 

where icon-number is an integer-expression taking a value from 0 to 3 and which governs the 
icon which is displayed: 0 for no icon, 1 for the Note icon, 2 for the Wait icon and 3 for the 
Stop icon. 

text-specs is up to five string-expressions separated by commas. These correspond to the five 
lines of text 



ALERT 

Use 

ALERT produces an alert box on the screen. 

Syntax 

ALERT icon(,] TEXT text-line[, text-line]... /./BUTTON button-spec], button-spec]... 

where: 

icon\ s an integer-expression giving a value in the range 0..3, specifying which icon is 
to be used. 0 specifies that no icon is required. 1 specifies the "Note" icon, 2 the 
"Wait" icon and 3 the "Stop" icon. 


Eachtext-line is a string-expression, giving one line of text for the body of the alert box. 
There may be at most five text-line s. Zero length strings are ignored. Strings longer 


than forty characters are chopped to forty characters. 

Each button-spec is /RETURN/ string-expression, giving the legend for one button in the 
alert box. There may be at most three button-specs, and only one may include the 
key word RETURN - indicating that the button is to be the "default" (the button 
assumed if the user presses return). 

Description 

ALERT takes all its parameters, constructs an alert box on the screen and waits 
for the user to respond. The ALERT command finishes when the user clicks on 
any of the buttons, or- provided a RETURN button is specified - when the user 
presses return. If there is more than one button in the alert then using ALERT as 
an assigned command will yield a value in the range 1 ..3, which gives what button 
was "pressed". 
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button-specs is up to three string-expressions separated by commas. These correspond to the 
three exit buttons. One string may be preceded by the keyword RETURN to indicate that it is 
the default exit button. 

If there is more than one button in the Alert box, you can use the ALERT statement in an 
assignment to find out which exit button the user selects. The statement itself returns a value 
of 1, 2 or 3 depending on which exit button was selected. By using the statement in an 
assignment, you can use the returned value to determine how to proceed. 

For example: 

choice - ALERT 1 TEXT "The End of the World"."Is Nigh" 

BUTTON "Save all Files". RETURN "Stop"."Panic" 


will produce: 


1 The End of the World 

Save all Files 

W Is Nish 


* 

\ Stop \ 


1 Panic 



choi ce is 1,2, or 3 according to the button pressed. 



-rr 

—ri 
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Chapter 15 mam 

File Handling 


File handling is a task that you might normally expect to carry out using operating system 
statements. This chapter describes the file handling that you can carry out from within 
BASIC 2 Plus. It assumes that the operating system you are using is some form of DOS. 

The facilities provided within BASIC 2 Plus are very much the same as those provided by the 
operating system. Using BASIC 2 Plus statements and functions, you can: 

• list the files in any directory on a disc 

• search for particular files 

• display the files themselves 

• select the current drive and the current directory 

• erase files; rename files 

• create new directories; remove existing directories 

just as you can using operating system commands. Indeed, many of the statements have 
exactly the same name and the same parameters as the equivalent operating system 
command. For example, if you need to list the files in the current directory, you can use 01R; 
if you want to erase a file, you can use ERASE or DEL. 

Other statements and functions (described in Section 15.5, below) allow you to use GEM'S 
Item Selector Dialog box to identify the file the program is to work with. 

The remaining statements and functions provide either additional facilities (eg. searching for 
particular files) or special versions of standard actions (eg. listing the directory to a particular 
stream rather than to the Dialogue window used by DIR). 

IMPORTANT: In what follows, the parameters of the disc statements are shown either as 
rest-oNine or string-expression. 

Statements shown as using rest-oNine can only be used as the last instruction in a program line 
or as a statement in the Dialogue window and any output they produce will always be in the 
Dialogue window. While these statements can be used within programs, they are really 
intended for use as immediate statements, for example when debugging: they use the 
Dialogue window so as not to interfere with any program output. 


Statements using a string-expression can be used anywhere and behave as normal 
BASIC 2 Plus statements. 
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Naming 


A file is referred to by its 'file name', which is: 

[drive:]N[pattA]file 

drive is a single letter, specifying the drive the file is on. If omitted, the current drive is 
assumed. 

path is a sequence of one or more directory names, separated by \ characters. The special 
directory name .. specifies the parent of the directory which precedes it in the path. 

path is used to specify the route to the directory containing the file, when it is not in the 
current directory. If path is preceded by a \, the route starts in the 'root' directory, otherwise it 
starts in the current directory. If omitted, the current directory on the current (or specified) 
drive is assumed. 

tile is the name of the file as displayed when its directory is listed; it may include an optional 
extension, for example, metal. seq 

Note that 'hidden' and 'system' files will be invisible to BASIC 2 Plus. 

A 'directory name' is specified as: 

[driveiMpath^U 

If null, the current directory is assumed. The terminating \ is optional, except in statements 
which may also take a file name as an argument, when it must be used to show that the 
argument is a directory, not a file. 

For further details of drives, directories, file specifiers and file naming, refer to your DOS 
user guide. 

15.1. Examining files 

When finding out about the files on a disc, you will usually want to inspect their names. To 
display these names, use either 01R or FI LES: 

OIR [rest-cl-tine] 

FILES [tt stream, J string-expression 

FI LES lists the files to the default stream or specified stream. DIR lists them to the Dialogue 
window, as described previously. 

For both of these statements, a parameter will limit the names listed. If it is a directory name 
(which must end with \), all files and subdirectories in that directory will be listed. If it is a 





















Use 

Syntax 

where 

Description 


Use 

Syntax 

where 

Description 


file name (which may include wildcards: see your DOS user guide for details), all files 
matching that name will be listed. If omitted or a null string, all files in the cunrent directory 
will be listed. 

If the file you are interested in is a text file, you can examine the file more closely by using 
the statements T Y P E or DIS P LAY to display the contents of the file: 

TYPE rest-of-line 

DISPLAY f# stream.] string-expression 

rest-of-line or string-expression specify the file's name explicitly: wildcards cannot be used. 

files & DIR 

These statements produce directory listings. 

FILES [tf stream-number. ] (file-filterj 

DIR rest-of-line 

Sle-fiiter is a string-expression 

rest-of-iine is everything up to the end of the line 

FI LES produces a list of the file names which match the %®er. The list is sent to 
the specified stream, or to the default stream if none is specified. The stream may 
not be random or keyed. DIR produces a list of the file names which match the file 
filter given by rest-of-line. The list is sent to the Dialogue Screen. 

FILES is the recommended form for use in programs. DIR is equivalent to the 
DOS command of the same name, and is really provided for use in Direct Mode. 

DISPLAY & TYPE 

These statements list the contents of a file. 

DISPLAY $ stream-number, [file-name 
TYPE rest-of-line 

rest-of-rme is everything up to the end of the line 

DISPLAY copies the given file to the specified stream, or to the default stream if 
none is specified. The stream may not be random or keyed. TYPE copies the file 
whose name is given by rest-oNine to the Dialogue Screen. 

DISPLAY is the recommended form for use in programs. TY P E is equivalent to the 
DOS command of the same name, and is really provided for use in Direct Mode. 
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DISPLAY lists the file to the default stream or specified stream. TYPE displays the file in the 
Dialogue window. 

Do not use TYPE or DISPLAY to print non-text files or directories, as the results will be 
unpredictable. 

15.2. Moving round the discs 

Where the files the program is to use are stored on different discs or in different directories, it 
is useful to be able to: 

• move from one disc to another (either in the same drive or in a different drive), and 

• change the current directory 

from within the program itself. 

Moving from one disc to another 

If the disc you want to use is in a different drive, you can change the default drive used by 
BASIC 2Plus by using DRIVE: 

DRIVE drive 

drive is a string expression, the first character of which is taken as the new drive letter. 

Changing the current directory 

To change the current directory, use the statements CD or CHDIR: 

CD rest-oNine 
CHDIR string-expression 

where rest-oNine or string-expression specifies the new current directory. 

To find the name of the current directory, use the function CHDI R$: 

CHDIRS ( string-expression ) 

The first character of string-expression specifies the drive whose current directory is to be 
returned. The parameter (together with its brackets) can be omitted; if so the current directory 
on the current drive will be returned. 
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DRIVE 

DRIVE sets the current drive. 

DRIVE drive 

drive is a string-expression, giving a single character string. 
Description DRI VE sets the current drive to be that given by drive. 


Use 

Syntax 

where 


Use 

Syntax 

where 

Description 


Use 

Syntax 

where 

Description 


CHDIR&CD 

These statements change the current directory. 

CHOIR file-name 
CD rest-of-iine 

rest-of-line is everything up to the end of the line 

CHOIR changes the current directory as specified by fife-name. 

CD changes the current directory, or reports the current directory to the Dialogue 
Screen, as specified by rest-oNine. 

CHDIR is the recommended form for use in programs. CD is equivalent to the DOS 
command of the same name, and is really only provided for use in Direct Mode. 

; 

CHDIR$ 

CHDIR$ is a function which returns the current directory. 

CHDI RiJidrive)) 

drive is a string-expression, giving a single character string. 

CH DI R$ returns a string containing the name of the current directory for drive, or for 
the current drive if the parameter is omitted. 


in 
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15.3. Disc housekeeping 

Within a BASIC 2 Plus program, you can; 

• erase files 

• rename files, and 

• create or remove directories. 

To delete a file or files, use the statements ERASE, DE L or KILL: 

ERASE rest-of-line 
DEL rest-oNine 
KILL string-expression 

rest-oNine or string-expression specifies the name of the file or flies to be erased. Multiple flies 
may be deleted by using wildcards in the name; however, you are not permitted to delete *. * 
(ie. all the files in the current directory). 

To change the name of a file, use the statements REN or NAME: 

REN rest-of-line 

NAME string-expressionl AS string-expression2 

REN interprets the rest of the line as two DOS filenames and renames the file with the first 
filename so that it is given the second filename. Similarly, NAME changes the name of the file 
named string-expressionl to string-expression2. An error will result if the the file does not exist 
or a file already exists with the new name. 

If a the first file name has a path specified but the second does not, the path is implicitly 
applied to the second name regardless of the current directory. However, if a path is given on 
both names, the file can be renamed into a different subdirectory (but not a different disc). 

To make a new directory, use the statements MD or MKOIR: 

MD rest-of-line 
MKDIR string-expression 

rest-oNine or string-expression specifies the name of the new directory. 

To delete (remove) a directory, use the statements RD or RMDIR; 

RD rest-oNine 
RMDIR string-expression 

Rest-oNine or string-expression specifies the name of the directory to delete. You must remove 
all the files from a directory before you delete it 
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KILL, ERASE & DEL 

Use These statements delete files. 

Syntax KILL file-filter 

ERASE rest-of-line 
DEL rest-of-fine 

where file-filter is a string-expression 

rest-of-line is everything up to the end of the line 

Description KILL deletes all files which match the file-filter. 

ERASE and DEL delete all files Which match the file filter given by rest-of-line. 

KILL is the recommended form for use in programs. ERASE and DEL are quivalent 
to the DOS commands of the same name, and are really only provided for use in 
Direct Mode. 

NAME & REN 

Use These statements change the name of a file. 

Syntax NAME old-file-name AS new-file-name 
REN rest-of-line 

where old-file-name and new-file-name are file-name s 

rest-of-line is everything up to the end of the line 

Description name changes the name of the file currently called old-file-name to be new-file-name. 

REN takes the file names given by rest-of-line and renames the file of the first name 
as the second name. 

NAME is the recommended form for use in programs. REN is equivalent to the DOS 
command of the same name, and is really only provided for use in Direct Mode. 


i/9 
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Use 

Syntax 

where 

Description 


Use 

Syntax 

where 

Description 


Use 

Syntax 

where 

Description 


MKDIR & MD 

These statements make a new directory. 

MKDI R file-name 
MD rest-of-line 

rest-of-line is everything up to the end of the Jine 

MKDIR makes a new directory called file-name. 

MD makes a new directory with the name given by rest-of-line. 

MKDIR is the recommended form for use in programs. MD.is equivalent to the DOS 
command of the same name, and is really only provided for use in Direct Mode. 

RMDIR&RD 

These statements delete (remove) a directory. 

MDIR file-name 
RD rest-of-line 

rest-of-line is everything up to the end of the line 

RMDIR deletes the directory called file-name. 

RD deletes the directory with the name given by rest-of-line. 

RMDIR is the recommended form for use in programs. RD is equivalent to the DOS 
command of the same name, and is really only provided for use in Direct Mode. 

FIND$ & FINDDIR$ 

These functions are provided for finding files and directories. 

FI NO* ( file-filter [, ordinal]) 

FINDDIR SUIeJMer [, ordinal]) 

file-filter is a string-expression 

ordinal is is an integer-expression, giving a value in the range 1 ..32767 

FIND* searches for the ’nth' file whose name matches the file-filter, where 'rf is 
given by ordinal, oris 1 of no ordinal is specified. If there is such a file then FIND* 
returns its name, otherwise a null string is returned. 

FINDDIR* is similar, but looks for directories. 
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15.4. Searching the disc 

BASIC 2 Plus functions can be used to check whether specific files and directories exist 
These functions can also be used to find files and directories that have names which match a 
given name template. 

The function to use to search for a file is FIN D$: 

FI ND$ ( string-expression[. n]) 

where string-expression specifies the name of the file to be searched for or, with wildcards, to 
specify the template that the filename should match; the optional n is an integer expression 
specifying that the nth file matching the string-expression should be searched for; the value 
relumed is a 12-character string giving the name of the matching file, if found, or a null 
string, if not found. 

For example, to check if there is a file with the type 'BAS' on the disc: 

IF FIND$("*.BAS”) - "" THEN PRINT "Not found" 

To find the name of the second file in the current directory: 
files - FINDS("*.*”,2) 

To search for a particular directory, use the function FINDDIRS: 

FINDDIRS ( string-expression[.np 

string-expression specifies the name of the directory to be searched for (again, wildcards may 
be used to specify a name template). The optional n is an integer expression specifying that 
the nth directory matching the string-expression should be searched for. 

The value returned is the name of the matching directory, if found, or a null string, if not 
found. 
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15.5. Using the Item Selector Dialog 

The Item Selector Dialog is a standard feature of GEM which allows the user to pick out the 
file the program is to work with. The SELECTOR statement allows BASIC programs to invoke 
an Item Selector' Dialog, and use the result. (It is because it is a standard feature that we use 
GEM's American spelling of the word Dialogue'.) 

GEM’S Item Selector Dialog takes two strings as parameters, the Directory string and the 
Selection string. The Directory string sets both the directory from which the selection is to be 
made, and which files in that directory are eligible. The Selection string is the name of the 
currently selected file (including the filetype, but excluding the directory part of the 
pathname). When the Dialog is displayed, the user can change either of these strings, and 
then leave the Dialog by 'Ok' or 'Cancel' buttons. 

BASIC 2 Plus's SELECTOR statement takes two string parameters. The first sets the initial 
value of the Directory string, the second the initial value of the Selection string. Using the 
'assigned statement' form it is possible to tell whether exit from the Dialog was by Ok or 
Cancel. For example: 

r-SELECTOR "\GMCH\*.TXT”. "HISCORE.TXT" 

will invoke an Item Selector Dialog which initially shows files with type TXT in the directory 
\GMCH\ on the current drive. The initial selection is the file HISCORE.TXT. The variable r 
will be set to zero if the user chooses the Ok exit, and to -1 if Cancel is chosen. 

In order to use the result of the Item Selector Dialog, three functions are provided - 
SELPATHS, SELWILDS and SELFILES - which are used to return values of three internal 
variables maintained by BASIC 2 Plus. 

SELFILES returns the filename of the selection. It includes the filetype, but 
excludes the directory part of the path name. 

SELPATHS returns the first part of the string - the path name portion, which 
specifies the drive and directory in which the selected file resides. 

The full name of the file selected is, therefore, SE LPATHS+SELFI LES. 

SELWILDS returns the last part of the Directory string - the file name portion, 
which usually contains 'wild card’ characters and which specifies 
which files in the SELPATHS directory are eligible for selection. 

The Directory suing which BASIC 2 Plus passes to GEM's Item Selector Dialog is thus 
SELPATHS + SELWILDS 
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SELECTOR 

Use SELECTOR runs an "item" selector dialogue. 

Syntax SELECTOR directory-string [, selecSon-string] 

SELECTOR , selection-string 

Description SELECTOR runs an "item" selector dialogue, so that the user can select a file. The 
"Directory" line in the dialogue is set from the directoryi-stringi or, if none is given, to 
the value last stored. The "Selection" line in the dialogue is set from the selection^ 
string, or, if none is given, to the value last stored. The user ends the dialogue by 
clicking on "CANCEL" or in a number of other ways which all mean "OK". 

II the dialogue ended "OK” the current states of the "Directory" and "Selection" 
strings are stored away. If the dialogue ended "CANCEL" the current states of the 
"Directory" and "Selection" strings are discarded-- the stored values are 
unaffected. 

I if a SELECTOR statement is assigned it returns the values -1 for "CANCEL" and 0 
■ for "OK". :v • ^•' 



SELPATH$ & SELFILE$ & SELWILD$ 



Description SELPATHS returns the directory name part of the "D irectory" line. S EL FI LE $ returns 
the "Selection" line. Note that SELPATHS+SELFI LE$ is the full name of the file 
■' selected.-.." • ■ 


SELWlLo$ returns the balance of the "Directory" line not returned by SELPATH*. 

_ - -■ • - -■ : ■ _ ■ 
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or 


The following example shows the use of a SELECTOR statement to get from the user the name 
of a file, which is then opened for Input: 

r-SELECTOR "\GMCH\*.TXT". "HISCORE.TXT" 

IF r<>0 THEN STOP ’STOP if Dialog Cancelled 
OPEN #5 INPUT SELPATHS+SELFILES 

When a SELECTOR statement is obeyed, the appropriate parts of its parameters are assigned 
to the variables associated with SELPATHS, SELWILDS and SELFILES. The Dialog is then 
invoked and given SELPATHS + SELWI LD$ and SELFI LE$ as its parameters. 

The user can then manipulate the file names displayed in the Dialog box before exiting. If the 
Ok exit is taken, the interpreter variables are overwritten with any new values set by the user. 
If the Cancel exit is taken, the variables are left as the values initially displayed in the box. 

The parameters for the SELECTOR statement are, in fact, optional. If a parameter is omitted, 
thenSELPATHS + SELWILDS and SELFILE) aroused. 

When BASIC 2 Plus is invoked (that is, before any SELECTOR statement has been executed) 
the path is set to the current directory, the wild part is set to *.* and the file selected is set to 
the null string. 



The full syntax for the SELECTOR statement is: 

SELECTOR [directory-portion],selection-portion 
SELECTOR 

Both parameters are string expressions. If the directory portion ends in a \, then *. * is added 
to it. If not, the tail of the directory portion is assumed to be a file name. 

Lastly, a group of OPTION statements is provided to force the various interpreter variables to 
take new values: 

OPTION SELPATHS string-expression 
OPTION SELWILOS string-expression 
OPTION SELFILES string-expression 
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15.6 Information about the System 

There are two functions which can be used to obtain information about the system you are 
using: VERSION and ENVIRON}. 

ENVIRON} returns a DOS environment suing. It takes one parameter, which may either be an 
integer or a suing. If it is a string, the suing should be the name of a DOS environment suing. 
In this case ENVIRON} returns that environment suing, without the name or the equals sign at 
the front. (If the string parameter is not the name of a DOS environment string, ENVIRON} 
returns the null suing.) 

If the parameter supplied is an integer n, ENVI RON} returns the n-th environment suing, but 
including the name and the equals sign. For example: 

ENVIRON}("PATH") 

might return the string 
\:C:\;C:\AP PS\BIN 

But ENVIRON}! 1) would return 
PATH =\;C:\;C:\APPS\BIN 



ENVIRON$ 

Use 

ENVI RON} is a function which yields information from the "environment* in the 

: 

form of a string 

Syntax 

ENVIRON}! argument) 

where 

argument is either an integer-expression, giving a positive, non-zero, value, 
or a string-expression. 

Description 

ENVI R0N$ returns a string from the DOS "environment". If the argument is an 

:'Vj; ; . / \• j;. ’: : : > :' : 

integer-expression, the ’nth’ environment string is returned. If the argument is a string- 


expression, the environment string with that name is returned. 


1 

f 
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VERSION has only one important use: finding out which version of DOS you are using. The 
syntax for this is 

VERSION(4) 

which returns an integer giving the version number as returned by the DOS function Get DOS 
Version Number. This is in DOS's own format, and will need to be converted. The following 
line shows by example how this may be done: 

PRINT VERSIONS) MOD 256 : : VERSIONS) \ 256 



VERSION 

Use 

VERSION is a function which returns version information. 

Syntax 

VERSION(|ue»y) 

where 

query is an integer-expression, giving a value in the range 0..4. 

Description 

VERSION returns an integer whose meaning depends on the value of query as 


follows: 



0 

return = 16, for 16 bit processor 


1 

return = 0 for full interpreter, 1 for "Run-Only" 


2 

return = 1 for Single User Environment, 2 for Multi-user Environment 


3 

return = 2 for DOS version 


4 

return = DOS version information, as given by DOS 














Error Trapping 



BASIC 2 Plus distinguishes two kinds of errors in a program: pre-scan errors and run-time 
errors. Pre-scan errors are those which are detected when the program is given its preliminary 
check by the interpreter. They include syntax errors and most type mis-matches. Run-time 
errors are those which do not come to light until the actual execution of the program. They 
include various programming errors (such as division by zero, or writing output to a file 
which has not been opened) and also certain user errors (not typing input in the correct form, 
for example, or putting the wrong disc in the drive). 

This chapter is concerned with how BASIC 2 Plus handles run-time errors; pre-scan errors 
are dealt with in Part 1 of this guide. Usually you will want your program to stop when an 
error is detected. You will want to inspect the code at the point where the error occurred so 
that you can adjust the program to prevent the error occurring again. 

Sometimes, though, you will want BASIC 2 Plus to report the error (or take some other 
action) and then continue with the rest of the program. This chapter describes how to do this. 

There are three main methods of dealing with run-time errors (other than the default action of 
letting the program stop and displaying an alert): 

• you can assign a return value from a statement to a variable 

• you can invoke an error trapping procedure 

• you can request that the error be referred back to the calling routine 

The next three sections deal with each of these methods in turn. 

You should note, though, that error trapping is not an alternative to the more conventional 
methods of avoiding errors, but should only be used as a last resort for errors that you either 
have not anticipated, or that you cannot avoid using the methods described here. This will 
make your programs easier to understand, test, and redesign. Error trapping should mainly be 
used as a last-ditch attempt to stave off loss of data, in crucial applications such as updating 
large keyed files, where premature termination of the program could be very inconvenient. 
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16.1 Assigned Statements 

We have already seen in Chapter 2 how statements can be assigned. Assigned statements look 
like this: 

error_state - LET share - coconuts \ sailors 

When an assigned statement is executed, the right-hand side is performed (if possible), and 
the return code from the operation is assigned to the general-variable on the left-hand side. A 
return code of 0 indicates that the statement was an unqualified success; any other number 
indicates a problem of one kind or another. Statements later in the program can test the 
general-variable in order to determine what went wrong and what action should be taken. 

• A return code of1000 or more indicates a pre-scan error while loading a module. 

• A return code from 100 to 999 indicates a BASIC 2 Plus error - an error which would 
normally be fatal and cause execution to stop. 

• A return code of 0 indicates unqualified success. 

Any other value shows a'qualified success'. This means that there is a problem, though not 
one which would ordinarily terminate the program. For example, in a random file, the 
statement POSITION NEXT advances the position one record along the file. But if the 
position is already at the end of the file, this is obviously not possible. Instead, the position is 
unchanged, and if the POSITION NEXT statement is assigned to a general-variable, that 
general-variable takes the value 2. (If the statement is not assigned to a general-variable, no 
error is raised.) 

Assigned statements never halt the program; the assignment is always made (though the 
statement forming the right-hand side of the assignment may not be executed). The flow of 
control always proceeds to the next statement in the usual way. 


16.2 Error Traps 

Another way of intercepting errors is by means of error trapping. This is introduced with the 
command 

ON ERROR GOTO location 

where location is defined somewhere in the same program body, module body, or routine. 

After this command has been issued, any errors will cause control to be transferred 
immediately to location, rather like the way control is transferred by a GOSUB. The program 
then continues in 'error state 1 , a condition which continues until a RESUME statement is 
executed. There are various forms of RESUME; they are explained below. The exact action 


286 
















Chapter 16: Error Trapping 






taken on a RESUME depends on which form is used. But if an ON ERROR GOTO is executed, 
some form of RESUME must be executed before any END or EXIT statement (such as END 
FUNCTION or EXIT MODULE). 

Any errors raised while the program is in error state always cause the program to stop (unless 
they are assigned). You cannot have error trapping inside an error trapping routine. 

Like subroutines, error trapping is local to the SUB or FUNCTION in which it is defined. You 
cannot directly access an error handler in another routine or module (though see ON ERROR 
EXIT). 

Error trapping can be cancelled with the statement 
ON ERROR STOP 

This causes the program to revert to stopping at errors and displaying an alert (In BASIC 2 
Plus's predecessor, BASIC 2, this command was ON ERROR GOTO 0.) 




ON ERROR 

Use 

ON ERROR specifies what action is to be taken in the event of an error. 

Syntax 

ON ERROR STOP 

or 

ON ERROR GOTO location 

or 

ON ERROR EXIT place 

where 

place is MODULE, SUB or FUNCTION, as appropriate. 

Description 

ON ERROR sets the action to be taken in the event of an error in the current 

MODULE, SUB or FUNCTION, overriding any previously set action. 


ON ERROR STOP re-instates the default error action, that is to stop the program 
and report the error. 


While an ON ERROR GOTO location is in force any error in the current MODULE, 

SUB or FUNCTION triggers an entry to "error state" and a jump to the given 
location. Statements are executed in "error state" until a RESUME statement is 
executed. Note that any error encountered while in "error state" provokes the 
default error action. Note also that it is an error to attempt to exit the current 
MODULE, SUB or FUNCTION while in "error state". 


While an ON ERROR EXIT place any error in the current MODULE, SUB or 

FUNCTION causes an immediate EXIT place . The error is then raised as if it had 
occured in the statement which invoked the MODULE, SUB or FUNCTION. 
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16.3 Refer to calling Routine 

When eiror trapping inside a SUB, FUNCTION, or MODULE, you can only use ON ERROR GOTO 
to divert the flow of control to a location inside the routine. If you want to handle errors 
outside the routine, you should use the appropriate one of the commands: 

ON ERROR EXIT SUB 
ON ERROR EXIT FUNCTION 
ON ERROR EXIT MODULE 

Once one of these commands has been executed, errors encountered inside the SUB, 
FUNCTION, or MODULE, will cause the routine to terminate, transferring control back to the 
calling statement immediately. The action taken there will depend on the error trapping state 
in the calling routine; it will be exactly as if the calling statement itself contained an error. 

ON ERROR GOTO,ON ERROR EXIT.andON ERROR STOP are of equal priority; a program's 
action on error is determined by the last one of these commands to be executed in the relevant 
routine. 

16.4 Resuming After Error 

After an error has been trapped by an ON ERROR GOTO statement, the only way to leave the 
error state is by means of RESUME. This section describes the various forms of the RESUME 
statement 

The statement RESUME, on its own, clears the error state and returns control directly to the 
beginning of the error-raising statement ready for it to be executed again. This is useful when 
some statement executed in the error-trapping pan of the program has changed the 
environment in such a way that the error-raising statement will not repeat the same error. 

RESUME NEXT 

clears the error state and returns control to the statement following the error-raising 
statement. (Should this be the THEN part of an IF statement, it is executed, and any ELSE 
pan is skipped.) 

RESUME location 

clears the error state and returns control to the line number or label location. In common 
with all means of transferring control to a named or numbered location, the destination 
must not be in a different SUB. FUNCTION or MODULE. 
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RESUME 

Use RESUME signals the end of "error state". 

Syntax RESUME 

or RESUME NEXT 
or RESUME till place 
or RESUME location 
or RESUME STOP 

where place is MODULE, SUB or FUNCTION, as appropriate. 

Description RESUME is valid only while in "error state", that is while executing statements 

following an error which occured while an ON ERROR GOTO location was in force. 
To leave "error state" a RESUME statement must be executed, and this specifies 
where or how to continue now that the error has been dealt with : 

RESUME - at the beginning of the statement in which the error occured. 
or RESUME NEXT- at the statement following that in which the error occured. 
or RESUME EXIT place -by leaving the MODULE, SUB or FUNCTION 
or RESUME location-at the given location. 
or RESUME STOP-by stopping and reporting the error. 


RESUME STOP 

transfers control back to the error-raising statement, but immediately stops and displays 
the alert for the error concerned. It is as if the ON ERROR GOTO had not been executed. 

Lastly, the statements 

RESUME EXIT SUB 
RESUME EXIT FUNCTION 
RESUME EXIT MODULE 

clear the error condition and immediately exit the SUB, FUNCTION, or MODULE currently 
being executed. In the case of a FUNCTI ON, it returns the last value assigned to the function 
name, exactly as if an ordinary EXIT FUNCTION had been executed. 

r 
r 
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Errors when debugging 

When you are debugging your program, you will normally use the various facilities described 
in the User Guide: Trace mode, debug points, and so on. But there are some BASIC 2 Plus 
functions which are useful, especially when testing an error trapping routine. 

If you need to deliberately raise an error, the statement 
ERROR integer-expression 

raises an error with the given return code. 

To find out how BASIC 2 Plus responds to a given error, use the function 
ERRORS ( integer-expression ) 

This yields the message displayed when a particular error is raised. 

When an error is raised the error number can be found with the function ERR. An error 
number of 100 signifies an operating system error - an error raised at too low a level for 
BASIC 2 Plus to provide any useful information directly. If this happens, OSERR returns the 
operating system's own error number to give you some help in ascertaining exactly what 
went wrong. 
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ERR 

Use 

ERR is a function which returns the number of the latest error. 

Syntax 

ERR 

Description 

ERR may be used when handling errors to establish what error has occured. 


ERROR 

Use 

ERROR raises an error. 

Syntax 

ERROR integer-expression 

Description 

ERROR raises the error whose number is given by the integer-expression, which must 
give a value in the range 1 ..32767. BASIC 2 Plus deals with the error in the usual 
way. Note that if the error is not known then it will be reported as "Unknown 
error", but the error number is unaffected. 


ERRORS 

Use 

Syntax 

ERR0R$ is a function which returns the message associated with an error number. 

ERROR} ( integer-expression) 

Description 

ERROR} returns a string containing the message associated with the the error 
whose number is given by the integer-expression, which must give a value in the 
range 1 ..32767. Note that if the error is not known then ERROR} will return j 

"Unknown error". 


OSERR 

Use 

OSERR is a function which gives more information about the latest "operating 
system dependent" error. 

Syntax 

OSERR 

Description 

Some statements, particularly file handling ones, encounter errors raised by the 
operating system for which there is no specific BASIC 2 Plus error. These 
generate the portmanteau "Operating System dependent" error - error number 

100. The function OSERR will then return a value (usually the Operating System’s 
own error number) to help identify the problem. 


09 


BASIC 2 Plus: Language Reference 
















292 




















Appendix I 

Character Set 


The table on the following page shows the Character Set BASIC 2 Plus assumes. 

This is only the actual Character Set that you have available when BASIC 2 Plus is being 
used with GEM 3. While the major part of this Character Set remain available, some of 
the characters will be absent and others will be transliterated if you: 

• use BASIC 2 Plus with GEM 2, or 

• display BASIC 2 Plus programs directly from the operating system (ie. without loading 
GEM), or 

• either print output or list programs to a printer 

The parts of the Character Set that are affected are shaded on the table overleaf, with different 
types of shading being used to indicate for example the differences between the GEM 3 
and GEM 2 Character Sets. (What the different shadings mean is explained in the notes 
accompanying the table.) 

You are strongly recommended to limit the range of characters you use to ones that aren't 
shaded overleaf. Only use the shaded characters where you specifically need these. 
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Parts of the Character Set which may be affected when BASIC 2 Plus programs or output is 
displayed directly from the operating system (ie. without loading GEM), or sent to a printer 
IBM Character Set assumed). Note that 0 and 0 are correct on Norwegian versions of the 
IBM Character Set. 

Parts of the Character Set which are associated with different characters under GEM 2. 

Parts of the Character Set is not used at all by GEM 2. 



















































































i Appendix II 

Control Sequences 


The following table shows the various escape sequences which can be used when printing 
text Not all of these sequences are availiable on all output devices; specifically some are only 
meaningful when applied to a virtual screen. For details see Chapters 11 and 12. 

Sequence Effect 


ESC 

A 

move cursor up one line 

ESC 

B 

move cursor down one line 

ESC 

C 

move cursor forward one column 

ESC 

D 

move cursor backward one column 

ESC 

H 

move cursor to top left (‘home’) 

ESC 

I 

move cursor up one line, scrolling if necessary 

ESC 

Y y+31x+31 

move cursor to column x, row y 

ESC 

j 

save cursor position 

ESC 

k 

move to saved cursor position 

ESC 

E 

clear screen and move cursor to top left 

ESC 

J 

clear to end of text screen 

ESC 

K 

clear to end of line 

ESC 

L 

insert blank line 

ESC 

M 

delete line 

ESC 

N 

delete character 

ESC 

d 

clear from start of text screen to cursor 

ESC 

1 

clear whole line 

ESC 

0 

clear from beginning of line to cursor 

ESC 

b c 

set foreground colour 

ESC 

m 

enter lightened mode 

ESC 

n 

exit lightened mode 

ESC 

P 

enter reverse video mode 

ESC 

q 

exit reverse video mode 
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Sequence 


Effect 

ESC 

r 

enter thickened mode 

ESC 

u 

exit thickened mode 

ESC 

s 

enter underlined mode 

ESC 

t 

exit underlined mode 

ESC 

X 

enter italic mode 

ESC 

y 

exit italic mode 

ESC 

e 

make cursor visible 

ESC 

f 

make cursor invisible 

ESC 

V 

wrap at line end 

ESC 

w 

don't wrap at word end 
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Error Messages 



100 0/S request failed - see OSERR 

101 Undefined DEF function 

102 Uninitialized variable 

103 Undefined record 

104 Overflow 

105 Division by zero 

106 Invalid operation 

107 Underflow 

108 Improper or out of range value 

109 Subscript out of range 

110 Coordinate outside virtual screen 

111 Undefined array 

112 Record too long 

113 Array much too big 

114 Array already defined 

115 String not long enough 

116 String too long for destination 

117 CONST already defined 

118 String concatenation failed 

119 Invalid number in input 

120 Invalid string in input 

121 Input item too long 

122 GEN AES error 

123 Type mismatch 

124 Stream in use 

125 Stream not open 

126 Stream is of wrong type 
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128 Screen already in use 

129 Invalid drive 

130 Invalid file name 

131 Record already defined 

132 Record number too big 

133 Path not found 

134 File not found 

135 File already exists 

136 End of DATA met 

137 End of file met 

138 Disc is full 

139 File access denied 

140 Cannot delete current directory 

141 Record and index files are inconsistent 

142 Invalid record or index file 

143 Incorrect record size 

144 Position not found 

145 Bad position string 

146 Key type mismatch 

147 Current position is not set 

148 Current position not found 

149 Index already defined 

150 Index not defined 

151 Key Is not unique for record 

152 Key Is not unique 

153 Internal error 

154 Memory full 

155 BASIC stack overflow 

156 Line too long 

157 Not a valid saved program 

158 Cannot continue 

159 Unexpected statement 
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160 RESUME missing 

161 Graphics buffer full 

162 Lock list full 

163 Value does not match any CASE 

164 Cannot unload active module 

165 Module has not been loaded 

166 Module name mismatch 

167 Too many modules loaded 

168 Module already initialized 

169 Improper USING string 

1000 Statement not allowed here 

1001 Syntax error 

1002 CASE missing 

1003 END missing 

1004 Block terminating statement missing 

1005 THEN missing 

1006 Unexpected statement 

1007 Invalid numeric constant 

1008 Too many points specified 

1009 Type mismatch 

1010 Repeated or invalid keyword 

1011 Too many or too few subscripts 

1012 Wrong number, mode or type of parameters 

1013 Name already declared 

1014 Name undeclared 

1015 Line number or label already declared 

1016 Line number or label undeclared 

1017 Unsuitable statement for error trap 

1018 Cannot change a CONST 

1019 Invalid export list in binary module 
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Machine Code Modules 



This Appendix explains how modules suitable for importing into BASIC 2 Plus programs can 
be written in machine code. 

Naturally, you must have some understanding of machine code and assemblers before you 
can write machine code modules. This description does not try to give you that 
understanding, and if you need to learn about machine code to link with BASIC 2 Plus you 
should read an introduction to 8086 programming. 

Instead, this part of the manual describes the interface between BASIC 2 Plus and machine 
code, showing how information can be passed from one to the other. As is usual with 
machine code programming, you get little help from the interpreter. BASIC 2 Plus does 
hardly any checking to ensure the interface is coded consistently; any errors may crash the 
whole system, and you will need to restart it before you can continue. 

A machine code module, like a BASIC module, resides in its own file on disc. The format of 
the file is the standard Microsoft .EXE format, as produced by many standard assemblers. 
(However, since the file will not be directly executable it may be prudent to give the file 
name a type extension other than . EXE in order to prevent DOS from trying to execute it.) 

When a LOAD MODULE statement is executed, BASIC 2 Plus loads the code into memory 
and tests to see whether the module is in BASIC or machine code. If it finds the standard 
JEXE header block, it assumes the module is in machine code, and it calls the .EXE entry 
point. 

In a normal .EXE file, this gives the location at which execution of the code is to begin. In a 
BASIC 2 Plus module it gives the start address of a routine which must return a pointer to an 
export list, a linked list whose purpose and structure are explained in some detail below. 

As well as returning the far pointer to the export list in DX:AX, the routine must ensure that 
CX contains the ASCII string 'B2'. F, BX, and ES can be corrupted, but all other registers 
must be preserved. Lasdy, before the routine is called, two two-byte parameters are pushed 
onto the stack. (They are for future expansion.) They must be removed by the routine, for 
example by reluming with the instruction RETF 4. 

BASIC 2 Plus runs this code at the time the module is loaded and then sets up pointers into 
the list. It accesses these pointers whenever one of the module’s routines is used, so the list 
must not be altered or moved once the module is loaded. 
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General Structure of Routines 

Machine code routines have an interface very similar to Microsoft QuickBASIC, Pascal, 
FORTRAN, and, in certain circumstances, C: routines are far called; function results are 
returned in registers; parameters arc passed on the stack. (See the section Passing Parameters 
and Results for more details about these topics.) 

Entry & Exit Conditions 

On entry to the routine, registers DS and SS are equal, and flags CLD and STI are set 

On exit DI, SI, BP, DS and SS must be preserved, SP, IP and CS are updated by the RET, 
AX, BX, CX and DX may be corrupt if they are not used to return the result of a routine 
function, and ES may be corrupt. 

The flags CLD and STI must be set; all other flags are corrupt. 

Passing Parameters and Results 

Parameters to a routine or module body are passed via the stack. There are three ways this 
can be done; 

• Numeric parameters called by VAL or CONST are themselves passed directly on the stack. 

• Other numerics and all strings are copied into temporary locations and the far address of 
the location is passed on the stack. For VAR or REF parameters, the value in the 
temporary location is assigned back to the actual parameter when the routine returns. This 
is called call by value-result. 

• Numeric arrays, which can only be called by VAR or REF, have the address of the actual 
parameter passed on the stack. This method must be used with care, as occasionally 
BASIC 2 Plus’s arrays can be moved in memory. Specifically, any DOS call which 
allocates or frees memory will invalidate the parameter. 

Note that it is not possible to pass string arrays to a machine code module. 

Parameters (or their addresses) are pushed onto the stack in the order they appear in in the 
calling statement (read from left to right). They arc all word-aligned on the stack. 

When a module returns a function result there are two methods for passing back the result to 
the calling program; these correspond to the first two methods for passing parameters: 

• Numeric results can be passed back directly in registers: results of length 1,2,4, and 8 
bytes should be passed in registers AL, AX, DX:AX, or AX:BX:CX:DX respectively. 

• Alternatively, numeric results can (and strings and arrays must) be passed back via a 
location whose address is returned in register DX:AX. 
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It is not possible for a function to return an array. 

It is, of course, essential to specify which method of parameter- and result-passing is used. 
This is one of the pieces of information held in the parameter specification , a four-byte block 
in the export descriptor whose exact format is described below. 

Note that it is the responsibility of the routine to remove parameters from the stack before 
reluming. This can be done with RETF n. 


The Export List 

The export list comprises specifications for the information transferred between the module 
and the calling program. For each routine in the module, this information includes such 
things as the name of the routine, the number of parameters it expects, the form of those 
parameters and (if the routine is a function, not a sub) the result which is returned. This 
information is encoded in a structure called an export descriptor. There is therefore an export 
descriptor for each routine in the module and one for the module body itself. It is these export 
descriptors which are linked together into the export list 

The export descriptor for the module body must always be present, and it must come first in 
the list It is followed by the descriptors for the routines; they can come in any order. 


! The Export Descriptors 


r 

r 

r 

r 

i 

i 

r 


Each export descriptor in the linked export list has the following format 

Bytes 0..3 the far address of the next export descriptor, or 0 if this is the last descriptor in 
the linked list 


Bytes 4..7 the far address of the routine’s BASIC 2 Plus name; this should be in lower 
case, and terminated with a null character (ASCII 0). In the case of a string¬ 
valued function, the final $ must be omitted from the name. 


Bytes 8..11 the far address of the code for the routine; this should be terminated with a 
RETF in the usual way. 

Bytes 12.. 13 the number of parameters the routine expects. 


Bytes 14.. 17 the result specification (see the next section for the format). This should be 
zero if there is no result, ie. if the routine is a subprogram or the body of the 
module rather than a function. 


Bytes 18..21 the parameter specification of the first parameter. 
Bytes 22..25 the parameter specification of the second parameter. 
.....etc. 
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The Parameter and Result Specifications 

As can be seen from the previous section, each parameter or result specification consists of 
four bytes. The first (byte 0) holds information which appertains to BASIC 2 Plus, namely 
the method of passing the parameter (VAR, VAL, or whatever) and whether its type is 
numeric, string, or a numeric array. The method of passing the parameter is encoded in the 
high-order nibble (bits 7..4) and the parameter type in the low-order nibble (bits 3..0). 

The second byte (byte 1) holds machine-code information. It is also divided into two nibbles. 
The high-order nibble shows how the module is to interpret the information passed on the 
stack: whether it is a pointer to the parameter, a pointer to a copy of the parameter, or the 
parameter itself. 

(This does not imply a choice: the option is determined by the type of the parameter and 
whether it is passed as VAL, VAR, REF, or CONST - see the section Passing Parameters 
and Results above. There is only a choice to be made at this stage when the specification is 
for the result of a numeric function) 

The low-order nibble of byte 1 contains information about the format of the parameter: if it is 
a string, how the string is terminated; if it is a number, how the number is represented. 

Bytes 2 and 3 are used to specify the minimum length of the slot in which a string parameter 
is passed: see the section String Parameters below. 

The numbers used to code the various pieces of information are as follows: 

Byte 0, high-order nibble: 

0: Specification is result specification of a subprogram (ie. the routine is not a 
function, so there is no result to return). 

1: Specification is result specification of a function. 

2: Specification is parameter specification of a VAL or CONST parameter. 

3: Specification is parameter specification of a REF parameter. 

4: Specification is parameter specification of a VAR parameter. 

Byte 0, low-order nibble: 

0: Specification is result specification of a subprogram. 

1: Numeric parameter or result. 

2: String parameter or result. 

3: Numeric array parameter. (Arrays cannot be returned as results.) 
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Byte I, high-order nibble: 

0: Specification is result specification of a subprogram. 

1: Stack contains a copy of the parameter itself. (Or, in the case of a function result, 
registers contain a copy of the result.) 

2: Stack contains a pointer to a copy of the parameter. (Registers contain a pointer to 
a copy of the result) 

3: Stack contains a pointer to the parameter itself. 

Byte 1, low-order nibble: 

0: Specification is result specification of a subprogram. 

1: Parameter (or result) is a string, with length determined by a two-byte length word 
preceding the string itself. See the section String Parameters below. 

2: Parameter (or result) is a string, terminated by null character. See the section on 
String Parameters below. 

3: Parameter (or result) is a numeric, represented in one unsigned byte. 

4: Parameter (or result) is a numeric, represented in one signed byte. 

5: Parameter (or result) is a numeric, represented in one unsigned word (2 bytes). 

6: Parameter (or result) is a numeric, represented in one signed word (2 bytes). 

7: Parameter (or result) is a numeric, represented in one signed double word (4 
bytes). This is the usual INTEGER format 

8: Parameter (or result) is a numeric, represented in IEEE four byte floating 
point format 

9: Parameter (or result) is a numeric, represented in IEEE eight byte floating 
point format 

Other formats cannot be passed to machine code modules. 
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String Parameters 


Environment 


A problem arises when a string is passed as a VAR or REF parameter the routine may 
lengthen the string, and unless BASIC 2 Plus knows this in advance, lengthening the string 
may overwrite some crucial piece of memory. 

For this reason, bytes 2 and 3 of the parameter specification give the minimum number of 
bytes allocated for a string parameter. (If the parameter is not a string, or if the length of the 
original string is adequate to return the result, bytes 2 and 3 should be zero.) Any unused 
space is padded with blanks or nulls, according to how the length of the string is determined 
- see the next couple of paragraphs. 

Strings can be passed to a routine in one of two forms, depending on the low nibble of by te 1: 

In the first method, the string is preceded by a 2-byte word containing the length of the string. 
Any spare space in the memory allocation for the string is padded with spaces. For VAR or 
REF parameters, the length assigned back to the actual parameter is that defined in the 
preceding length word. 

In the second method, the string is also preceded by a 2-byte length word. Here, however, 
spare space in the memory allocation is padded with nulls. For VAR or REF parameters the 
length assigned back to the actual parameter is the length up to the first null. This is 
compatible with C. 


The machine code module is run in BASIC 2 Plus’s process. So the PSP, the file handles, the 
environment strings, the allocated memory, etc. all belong to BASIC 2 Plus. In particular the 
PSP will not be contiguous with the module. 

The module must not change any state that will affect BASIC 2 Plus; in particular it must not 
free any memory that it has not itself allocated, and it must leave the state of any file handles 
as it found them. 

Before the module is unloaded, it should free any memeory that it allocated and close any 
files that it opened. There is no implicit module shut-down mechanism, so any shut-down 
routine must be explicitly called from the BASIC 2 Plus program. 













INDEX 


ABS, 50 

Absolute value, 50 
ACOS, 54,55 
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Actual screen dimensions, 157 
actual-array, 3 
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ATN, 54,56 
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Binary arithmetic, 58 
Binary numbers, 16 
Bitwise arithmetic, 40 
Bitwise operator, 40 
Body 

of module, 123 
Boolean arithmetic, 39 
Boolean expression, 39 
Boolean operator, 39 


BOX, 197,198 
BUTTON, 266,267 
BYTE, 35 

CALL, 110 

CALL MODULE, 128,130 
CASE, 90,91 
CD, 274,275 
CEIL, 48,49 
CEILING, 48,49 
Character code, 82 
Character set, 293 
CHDIR, 274,275 
CHDIRS, 274,275 
CHRS, 82,83 
CINT.48 
CIRCLE, 199 
CLEAR RESET, 151 
CLOSE, 144 
CLOSE WINDOW, 259 
Closing a stream, 144 
Closing keyed files, 234 
Closing random file, 225 
CLS, 180,181,219 
COLOUR, 178,204 
Colour graphics, 204 
Command 
DOS, 271 

Comparing strings, 84 
Concatenating strings, 68 
CONSOLIDATE, 235 
CONST, 21,22 
CONST-paramcter, 112 
Constant, 15,18,22 
Numeric, 15 
String, 16 

Control character, 177 
Control sequences, 295 
Conversion error, 60 


Coordinate 
Device, 186 
User, 186 
COS, 54,55 
Creating Indexes, 236 
CURRENCYS, 176 
Current position, 224,226,238 
Cursor 

defining shape, 265 
making visible, 264 
position of, 152 

Dashed line marker style, 205 
DATA, 22,23 
DATE, 51,53 
DATES, 78 
DECS, 80,81 
Decimal arithmetic, 58 
DECLARE, 17,18 
DECLARE CONST, 129 
Declaring variables, 17 

DEF, 120,121 
DEF-function, 120 
Default graphics style, 206 
Default stream, 143 

DEG, 57 
Degrees, 57 
DEL, 276,277 
DELKEY, 246,247 
Device, 135 

Device coordinate, 186 
DIM, 26,27 
Dimension, 26 
DIMENSIONS, 28,29 
Dimensions of actual screen, 157 
Dimensions of virtual screen, 158 
DIR,272,273 
Directory 
changing, 274 
creating, 276 
deleting, 276 
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finding, 279 
DISPLAY, 273 
DISTANCE, 212,213 
Division 
integer, 38 
DO, 98,99 
DO loop, 98 
DO UNTIL, 98 
DO WHILE, 98 
DO.XOOP, 98 
DOS 

information from, 283 
DOS files, 271 
Dotted line marker style, 205 
DRIVE, 274,275 
changing, 274 

EFFECTS, 179 
ELLIPSE, 202 
ELLIPTICAL PIE, 202 
ELSE, 86 
ELSEEF, 86 
END, 104,205 
END IF, 86 
End of file 
detecting, 163 
ENVIRONS, 283 
EOF, 163 
EPS, 50,62,63 
ERASE, 276,277 
ERR, 289,290 
ERROR, 289,290 
conversion, 60 
rounding, 61 
Error trapping, 285 
ERRORS, 289,290 
ESC, 177 

Escape character, 177 
Escape sequence, 171,177,295 
EXIT DO, 102,103 
EXIT FOR, 102,103 
EXIT FUNCTION, 117 


EXIT MODULE, 130 
EXIT SUB, 117 
Exiting a loop, 102 
EXP, 45 

Exponentiation, 38 
EXPORT, 131 
Exporting, 131 
Expression, 3,41 
Boolean, 39 

Expression function, 120 
Expression function call, 121 
EXTENT, 222 

FALSE, 39,40 
FD, 212 
Field, 31 
field-selector, 4 
Files 

deleting, 276 
DOS, 271 
finding, 279 
keyed, 233 
random, 225 
renaming, 276 
File locking, 251 
filename, 4 
FILES, 272,273 
FILL, 205 
FILL ONLY. 205 
Fill options, 205 
FILL WITH, 205 
FINDS, 278,279 
FINDDIRS, 278,279 
FIX, 48,49 
FIXED, 35,148 
Flexible screen, 146 
Floating point arithmetic, 58 
FLOOD, 208,209 
Flood fill, 208 
FLOOR, 48,49 
Flow of control, 85 
Font, 215 
FONTS, 215 


FOR, 95,96 
FOR loop, 95 
Formal parameter, 111 
formal-array, 4 
formal-list, 4 

Formatted numbers, 81,173 
Formatted Output, 171 
Formatted print, 168,171 
Formatted strings, 172 
FORWARD, 211,212 
FRAC.49 

FREEFILE, 136, 137 
Function, 114,115 
function-call, 4 

General options, 204 
general-variable, 5 
GET, 224,230,240 
Global variable, 108,123 
GOSUB, 119 
GOTO, 104,105 
Graphic device 
opening, 140 
Graphics, 185,206,207 
colour, 204 
default style, 206 
transparent, 204 
Graphics origin, 189 
Graphics screen, 146 
Graphics styling, 204 
GRAPHICS UPDATE, 185 
GRAPHICS.. .RESTORE, 207 
GRAPHICS...UPDATE, 186 

HEADING, 212,213 
HEXS, 79 

Hexadecimal numbers, 16 
I/O 

sequential, 136 
identifier, 5 
IEEE4,35 






















IEEE8,35 
IF, 85 

IF (single line version), 87 
IF..END IF, 89 
IF..GOTO, 87 
IF..THEN, 87 
IMPORT, 128,129 
Import block, 128,129 
Importing a Module, 128 
Impossible Calculations, 59 
Indenting text, 182 
Index, 233 
array, 26 
creating, 236 
Information line, 150 
defining, 264 
INKEY, 164,165 
INKEY$, 164,165 
INPUT, 138,159,160 
from keyboard, 164 
sequential, 159 
INPUTS, 161,162 
INSTR, 72,73 
INT, 48,49 
INTEGER, 35 
Integer arithmetic, 58 
Integer division, 38 
integer-expression, 5 
Item Selector Dialog, 280 

KEY, 36,233,241 
adding, 244 
changing, 246 
deleting, 246 
KEYS, 241 
Keyboard input, 164 
Keyed file 
updating, 242 
Keyed files, 233 
KEYSPEC, 236,237 
KILL, 276,277 


label, 5 
LABEL, 12 
LBOUND, 28,29 
LCASES, 70,71 
Leading spaces 
removing, 70 
LEFT, 210,211 
LEFTS, 76,77 
LEN, 72,73 
Length 

of string, 72 
LET, 20,21 
Library, 124 
LINE, 195,196 
LINE INPUT, 161 
Line number, 12 
Line options, 205 
Line style, 205 
Line width, 205 
line-number, 5 
LOAD MODULE, 126,127 
LOC.226 
Local variable, 108 
LOCATE, 180,181,265 
location, 5 
LOCK, 253 
Locking files, 251 
Locking records, 252 

LOF. 229 

LOG, 44,45 
LOGIO.44,45 
LOG2,44,45 
Logarithm, 44 
Loop, 94,99 
LOWER, 29 
LOWERS, 71 
LPRINT, 182,183 
LSET.68,69 
LT.211 

LTR1MS, 70,71 


Machine code module, 133 
Main program, 12 
MARGIN, 182 
MARKER, 195 
Matching coordinates, 190 
MAX, 46 
Maximum, 46 

Maximum window size, 150 
MAXNUM, 50,51 
MD, 276,278 
Metafile, 185 
MIDS, 76 

MIDS-Function, 77 
MIDS-Statemcnt, 76 
MIN, 46,47 
Minimum, 46 

Minimum window size, 150 
MKDIR, 276,278 
MOD, 38 
MODE, 204 

Module, 12,123,124,125 
calling, 128 
importing, 128 
in memory, 133 
loading, 126 
machine code, 133 
unloading, 132 
MODULE, 123 
Module body, 123 
Mouse 

finding position, 266 
MOVE, 220,265 
MOVE FORWARD, 211 
Multi-user operation, 255 

name, 6 

NAME, 276,277 
National variants, 176 
Nested IFs, 88 
NEXT, 95,97 
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NOT, 39,40 
Numbers 
formatted, 81 
binary, 16,173 
hexadecimal, 16 
scaled, 16 

string representation of, 79 
Numeric constant, IS 
Numeric variable, 17 
numeric-expression, 6 
numeric-general-variable, 6 
numeric-identifier, 6 
numeric-literal, 6 

OFF, 40 
ON, 40 

ON ERROR, 286 
ON ERROR GOTO, 285 
ON ERROR STOP, 286 
ON..GOSUB, 120 
ON..GOTO, 94 
OPEN, 136,137 
OPEN WINDOW, 140 
OPEN... APPEND, 139 
OPEN...DEVICE, 141 
OPEN...GRAPHICS, 141 
OPEN...INPUT, 139 
OPEN...OUTPUT, 139 
OPEN...PRINT, 139 
OPEN...RANDOM, 227 
OPEN...WINDOW, 142 
Opening a stream, 136 
Opening a window, 140 
Opening keyed files, 234 
Opening random file, 225 
Operator, 37 
arithmetic, 37 
bitwise, 40 
Boolean, 39 
relational, 39 
unary, 38 

Operator precedence, 42 


OPTION ARITHMETIC 

DECIMAL, 59 
OPTION ARITHMETIC 

NATIVE, 59 
OPTION CURRENCYS, 176 
OPTION DECIMAL, 176 
OPTION DECLARE, 17 
OPTION DEGREES, 57 
OPTION RADIANS, 57 
OPTION TRAP, 17 
OPTION UNDERFLOW, 60 
OR, 39,40 
Origin, 189 
OSERR, 289,290 
OUTPUT, 138 
formatted, 171 
sequential, 167 
unformatted, 170 
Overflow, 59 
Overlaying, 123 

Parameters,! 11 
actual. 111 
CONST, 112 
formal. 111 
reference, 113 
VAL, 111 
VAR, 112 

Physical screen, 145 
PI, 50,51 
PIE, 201 
Pixel, 186 
colour of, 152 
PLOT, 195,196 
Point, 194,210,211 
Point size, 216 
Pointer 

defining shape, 266 
Points 

finding position, 266 
POINTSIZE, 216 
POS, 152,153 
POSITION, 226,228,238 



POSITIONS, 241 
Positioning text, 180,220 
Power, 38,44 

Precedence of operators, 42 
PRINT, 167,168 
formatted, 168,171 
unformatted, 168,170 
Print function, 167 
Print item, 167 
Print template, 167 
PROGFILES, 127 
PROGPATHS, 126,127 
Program unit, 12 
PUT, 224,231 

RAD, 57 
Radians, 57 
Random file, 225 
updating, 231 
Random numbers, 46 
RANDOMIZE, 46,47 
RD, 276,278 
READ, 24 

Reading records, 229,240 
Record, 31,33 
Record locking, 252 
Recursion, 118 
Redefining screen, 148 
Reference parameter, 113 
Relational operator, 39 

REM, 13 
Remark, 13 

REN, 276,277 
REPEAT, 101 
REPEAT loop, 100 
REPEAT..UNTIL, 100 
Repeating characters, 72 
REPOSITION, 248,249 
Reset windows, 151 
rest-of-line, 271 
RESTORE, 24,25 
RESUME, 287,288 
RETURN, 119 

























Return Code, 25 
RIGHT, 210,211 
RIGHTS, 76,77 
RMD1R, 276,278 
RND.46,47 
ROUND, 48,49 
Rounding error, 61 
Rounding functions, 48 
Routine, 107 
Routine function, 114 
Routine-function-call, 115 
RSET.68,69 
RT, 211 

RTRIMS, 70,71 

Scaled numbers, 16 
SCREEN, 148,149 
actual, 154 

dimensions of actual, 157 
dimensions of virtual, 158 
flexible, 146 
graphics, 146 
physical, 145 
redefining, 148 
size of actual, 154 
size of virtual, 152 
text, 146 
virtual, 145,152 
SCREEN GRAPHICS, 150 
SCREEN TEXT, 148 
SELECT CASE, 90,91 
selector, 6 

SELECTOR, 74,280,281 
SELFILES, 280,281 
SELPATHS, 280,281 
SELWILDS, 280,281 
Sequential Input, 159 
Sequential Output, 167 
SET, 218,219 
SET WRAP, 178 
SET ZONE, 170 
SGN, 50 


SHAPE, 197 
SHARED, 116,117 
Shared variable, 116 
simple-numeric-variable, 7 
simple-string-variable, 7 
simple-variable, 7 
SIN,54,55 
Single key input, 164 
SQR, 44,45 
Square root function, 44 
START, 205 
Statement, 10 
STEP, 95 
STOP, 104,105 
Storage class, 34 
STRS, 79,80 
Stream, 135,143 
closing, 144 
default, 143 
opening, 136 
stream-number, 7 
String, 67 
constant, 16 
formatted, 172 
substring of, 74 

String representation of numbers, 79 
String variable, 17 
STRINGS, 72,73 
string-expression, 7 
string-general-variable, 7 
string-identifier, 7 
string-literal, 7 
STYLE, 205 
Styles of text, 178 
SUB, 109 
Subprogram, 109 
Subroutine, 119 
Substring, 74 
testing for, 72 
substring-selector, 8,74 
SWAP, 22,23 
System 


information from, 283 

TAB, 169,171 
TAN, 54,56 
Template, 167 
TEST, 153,209 
TEXT, 152 
angled, 218 
colour, 214 
in different sizes, 216 
on graphics devices, 214 
positioning, 220 
TEXT CLEAR, 181 
TEXT DELETE, 181 
TEXT FEED, 180 
Text indenting, 182 
TEXT INSERT LINE, 181 
Text positioning, 180 
Text screen, 146 
Text styles, 178 
Text wrapping, 178,182 
THEN, 86 
TIME, 51,52 
TIMES, 78 
TIMER, 51,52 
Title bar 
defining, 264 
TOWARD, 212,213 
Trailing spaces 
removing, 70 
Transparent graphics, 204 
Trigonometry, 54 
TRUE, 39,40 
TRUNC, 48,49 
Truncation functions, 48 
truth-value, 8 
Turtle graphics, 210 
TYPE, 273 

UBOUND, 28,29 
UBYTE, 35 
UCASES, 70,71 
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Unary operator, 38 

WHOLES, 35,68,69 

YMOUSE, 266,267 

Underflow, 60 

WIDTH, 205 

YPIXEL, 154,155,191 

Unformatted output, 170 

Window, 145,258 

YPLACE, 262 

Unformatted print, 168,170 

fixed, 148 

YPOS, 152,153 

UNIQUE, 249 

manipulating, 257 

YSCROLL, 263 

UNLOAD MODULE, 132 

opening, 140 

YUS ABLE, 156 

UNTIL, 100 

restricted size, 150 

YVIRTUAL, 152,153,191 

Updating keyed files, 242 

WINDOW CLOSE, 257 

YWINDOW, 260,261 

Updating random files, 231 

WINDOW CURSOR, 264 


UPPER, 29 

WINDOW INFORMATION, 264 

ZONE, 170 

UPPERS, 71 

WINDOW OPEN, 140,257 

Zone size, 170 

User coordinate, 186 

WINDOW SCROLL, 263 


defining, 188 

WINDOW SIZE, 259 

0.74 

USER ORIGIN, 189 

WINDOW TITLE, 264 

71,50,51 

USER SPACE, 188 

WORD, 35 

USER...ORIGIN, 189 

Wrapping text, 178,182 


USER...SPACE, 189 
USING-string, 167,171 

XACTUAL, 260,261 


USING-template, 167,171 

XBAR, 262 


UWORD, 35 

XCELL, 220,221 


VAL, 53,54,111 

XDEVICE, 154,155,191 
XMETRES, 154,155,192,193 


VAL-parameter, 111 

XMOUSE, 266,267 


VAR-parameter, 112 

XOR.39,40 


Variable, 17 

XPIXEL, 154,155,191 


global, 108,123 

XPLACE, 262 


local, 108 

XPOS, 152,153 


numeric, 17 

XSCROLL, 263 


shared, 116 

XUSABLE, 156 


string, 17 

XVIRTUAL, 152,153,191 


Variable name, 18 

XWINDOW, 260,261 


Vector field, 31 

VERSION, 283,284 

YACTUAL, 260,261 


Virtual screen, 145,152 

YASPECT, 154,155,191 


Virtual screen dimensions, 158 

YBAR, 262 


VPOS, 152,153 

YCELL, 220,221 


WEND, 100 

YDEVICE, 154,155,191 

YMETRES, 154,155,192,193 



WHILE loop, 100,101 
WHILE..WEND, 100 
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